# Counts payload

> Every field the Collector sends to the service, with the rule the service checks.

Validated against app `ae3b0ef2` and Collector `0.9.0` (`54621da`), 11 November 2026.

Generated from `humanload/src/contract.ts`, `humanload/src/diagnostic-contract.ts`, `humanload/src/distribution.ts`, `humanload/src/dictionaries/en.ts`. This page changes only when that code changes.

The service refuses any key that is not on this page: every object is closed, and every text field is closed by
a pattern or a list of values. Each line gives a field, then the rule the service checks.
[What leaves your computer](/what-leaves-your-computer.md) explains the purpose of each field and names the
request headers.

## The batch of Counts

Sent to `POST /api/v1/ingest`, 35 Local days at most.

### The batch

- `schema`: whole number, 1 to 2. Meaning: the batch format version: 1 or 2.
- `collector`: text matching `^\d{1,3}\.\d{1,3}\.\d{1,3}$`. Meaning: the Collector version (x.y.z).
- `calc`: whole number, 1 to 1000. Meaning: the version of the Count computation, from 1 to 1,000.
- `days`: list of 1 to 35 items. Meaning: the local Days of the batch, 35 at most.

### Each Local day of the batch

- `day`: text matching `^\d{4}-\d{2}-\d{2}$`. Meaning: the date of the local Day (YYYY-MM-DD), without time or time zone.
- `observed_at`: whole number, 0 or more. Meaning: the sending time, truncated to the full hour; never the time of an event.
- `complete`: `true` or `false`. Meaning: is the local Day closed?
- `method`: `exact` or `estimated`. Meaning: exact (observed live) or estimated (History review).
- `counts`: object. Meaning: the thirteen Counts of the day and, in format 2, the four candidate-noise Counts.
- `note`: object. Meaning: absent, unless you turn on Evening note sync.

### The Counts of a day

- `interventions`: whole number, 0 to 2000. Meaning: Interventions: your messages to the sessions you lead.
- `project_switches`: whole number, 0 to 2000. Meaning: Project switches, 20 minutes apart at most.
- `session_switches`: whole number, 0 to 2000. Meaning: session switches, 20 minutes apart at most.
- `waiting_peak`: whole number, 0 to 100. Meaning: the peak of waiting Sessions.
- `asks`: whole number, 0 to 2000. Meaning: the agent's structured questions.
- `asks_answered`: whole number, 0 to 2000. Meaning: those that got an answer.
- `asks_decided`: whole number, 0 to 2000, or `null`. Meaning: Settled questions; null until the measurement is proven.
- `asks_recommended`: whole number, 0 to 2000, or `null`. Meaning: among them, those settled with the recommended option; null likewise.
- `permissions`: whole number, 0 to 5000. Meaning: the agent's Permission requests.
- `sessions`: whole number, 0 to 100. Meaning: the sessions with an Intervention that day.
- `concurrent_peak`: whole number, 0 to 100. Meaning: the peak of sessions led at the same time.
- `active_quarters`: whole number, 0 to 96. Meaning: the quarter-hours with at least one Intervention.
- `late_quarters`: whole number, 0 to 96. Meaning: among them, those between 11 pm and 5 am.
- `permission_noise`: object. Meaning: four integers from 0 to 5,000; absent in format 1, which does not measure this noise.

### `permission_noise`, only in format 2

- `repeated`: whole number, 0 to 5000. Meaning: temporary approvals preceded by three confirmed approvals for the same request, within 30 local Days.
- `permanent`: whole number, 0 to 5000. Meaning: confirmed permanent approvals.
- `observed`: whole number, 0 to 5000. Meaning: requests with a confirmed human decision; zero means no evidence received.
- `compound`: whole number, 0 to 5000. Meaning: requests for compound commands, without assuming their decision.

### `note`, only with Evening note sync

- `value`: whole number, 1 to 5. Meaning: the note, from 1 to 5.
- `source`: `evening` or `next_day`. Meaning: evening (the same evening) or next_day (the next day).

### Example

A batch the service accepts, with synthetic numbers:

```json
{
  "schema": 2,
  "collector": "0.9.0",
  "calc": 5,
  "days": [
    {
      "day": "2026-11-11",
      "observed_at": 1794391200,
      "complete": false,
      "method": "exact",
      "counts": {
        "permission_noise": {
          "repeated": 0,
          "permanent": 0,
          "observed": 0,
          "compound": 2
        },
        "interventions": 41,
        "project_switches": 6,
        "session_switches": 9,
        "waiting_peak": 2,
        "asks": 5,
        "asks_answered": 5,
        "asks_decided": null,
        "asks_recommended": null,
        "permissions": 7,
        "sessions": 4,
        "concurrent_peak": 3,
        "active_quarters": 22,
        "late_quarters": 0
      }
    }
  ]
}
```

### What the service answers

When the batch is stored:

- `id`: text matching `^[0-9a-f]{64}$`.
- `next_after`: whole number, 0 or more.
- `note_sync`: `true` or `false`.
- `backfill`: `true` or `false`.
- `epoch`: whole number, 1 or more.

When it is refused, one reason out of: `schema_version`, `calc_version`, `unknown_key`, `bad_type`, `bad_pattern`, `out_of_range`, `too_many_days`, `duplicate_day`, `day_window`, `future_timestamp`, `not_on_hour`, `estimated_not_closed`, `cross_invariant`.
The first two are version refusals (status 422); the others are refusals of form (status 400): 11 reasons.
A refusal never quotes the value received.

## Pairing

Sent once to `POST /api/v1/collector/enroll`, when you approve the Device:

- `platform`: `macos`.
- `collector`: text matching `^\d{1,3}\.\d{1,3}\.\d{1,3}$`.

## The receipt after a sending outage

Sent to `POST /api/v1/collector/recovery` once sending works again, one receipt per outage:

- `v`: always `1`.
- `id`: text matching `^[0-9a-f]{32}$`.
- `reason`: `dns` or `tls` or `connexion` or `reponse_invalide` or `login_access` or `jeton_refuse` or `introuvable` or `limite` or `schema_refuse` or `serveur` or `accuse_absent` or `config` or `identifiants` or `stockage` or `annulation` or `duree`, or text matching `^http_[1-5][0-9][0-9]$`.
- `started_hour`: whole number, 0 to 100000000.
- `completed_hour`: whole number, 0 to 100000000.
- `duration_s`: whole number, 0 to 31622400.
- `oldest_pending_s`: whole number, 0 to 31622400.
- `pending_peak`: whole number, 1 to 35.

A receipt the service accepts, with synthetic values:

```json
{
  "v": 1,
  "id": "0123456789abcdef0123456789abcdef",
  "reason": "dns",
  "started_hour": 498424,
  "completed_hour": 498441,
  "duration_s": 61200,
  "oldest_pending_s": 57600,
  "pending_peak": 2
}
```

## The capability check

Before a send that has work, and in `humanload doctor`, the Collector posts `{}` to
`POST /api/v1/collector/capabilities`. The service answers:

- `v`: always `1`.
- `recovery`: always `1`.
- `schemas`: the list `[1,2]`.
- `min_calc`: whole number, 1 to 2147483647.
