# Check telemetry and collection

> Check whether the measurements behind Health are fresh and browse each Number's snapshots.

Telemetry is the set of measurements Health is estimated from. Use it to check
whether a Number's evidence is fresh and to see what was measured at a given
time. A measured zero and **Not measured** are different results.

Telemetry holds bounded counts, booleans, enums, timing histograms and
error-code counts from a real Number connected as a linked device. It never
contains message content, media, recipient or contact identifiers, or chat
history.

## Before you begin

Use a team key or project token with `sessions:read`. A team key names the
project with `projectId`. A project token reads only its own project; another
project or Number returns `404`.

## Check collection status

**Console:**

On the project's **Safety** page, the **Data received** tab shows whether each
Number's latest record is up to date, out of date, on an unsupported version or
absent. Select a Number, open **Checks** and select **Show all measures** for
its periods and measures.

**API:**

```bash
curl "https://api.polymorfa.com/platform/bansafe/collection?projectId=$PROJECT_ID" \
  -H "Authorization: Bearer $POLYMORFA_API_KEY"
```

`GET /platform/bansafe/telemetry/{session}` returns the same status with one
Number's latest snapshot. See
[List collection status](https://docs.polymorfa.com/api/bansafe/list-ban-safe-collection).

| State | Meaning |
| --- | --- |
| `fresh` | The latest supported record is at most 10 minutes old. |
| `stale` | A supported record exists, but it is older than that. |
| `not_collected` | No record is kept. This does not mean collection is turned off. |
| `unsupported` | A record exists, but its version cannot be shown as a current measurement. |

`latestFlushedAt` is when the Number produced the record and
`latestReceivedAt` is when Polymorfa stored it. `freshUntil` is the end of the
freshness window. `droppedRecords` above zero means the collector reported a
gap, so the window is incomplete; missing activity is not counted as zero.

## Browse snapshots

`GET /platform/bansafe/signals` lists every signal with its `key`, label,
description, group, value kind and unit.

`GET /platform/bansafe/telemetry/{session}/history` returns snapshots newest
first. It accepts `since`, `until`, `cursor` and `limit` (default 10,
maximum 50). Follow `page.nextCursor` while `page.hasMore` is `true`.

Each snapshot has its bucket, flush and receipt times, whether the bucket was
partial, its record version, and its `signals`. A partial bucket is a normal
sub-hour snapshot.

| Signal field | Meaning |
| --- | --- |
| `measured` | Whether the snapshot holds a usable observation for this signal. |
| `value` | A number, boolean, enum value or histogram bins. Null when unmeasured or when `codes` holds the value. |
| `sampleSize` | How many observations stand behind a distribution or measurement. |
| `codes` | Bounded error-code counts for a `code_counts` signal. |

Show `measured: false` as unavailable for that snapshot, never as a clean
result. Histograms hold aggregate bin counts, not events.

## Calls and new contacts

Two signal groups describe outreach. Both hold counts only, never a callee or a
call identifier.

| Group | What it counts |
| --- | --- |
| `calls` | Calls the Number placed (`outbound`) and how they ended: `answered`, `declined`, `unanswered`, `failed`, and the `restricted` calls WhatsApp refused. `cold`, `warm` and `unknown` split callees by whether the Number had chatted with them. `heldByRestriction` counts calls Polymorfa refused while the Number was restricted. `inbound` counts calls received. |
| `reach` | People with no prior chat reached in the bucket: by message (`newContactsByMessage`), by call (`newContactsByCall`) and in total (`newContacts`). `newContactsMax10m` is the most reached in any ten minutes. |

A person counts once per UTC day, in the hour that first reached them, so the
hours of a day add up to distinct people. Divide `unanswered` or `declined` by
`outbound` for their shares. The cold-callee share is `cold` divided by
`cold + warm + unknown`; it covers calls that passed the restriction check and
reached WhatsApp. A call that failed before reaching WhatsApp is in neither the
callee split nor `reach`.

## See also

- [Read a Number's Health](https://docs.polymorfa.com/safety/health)
- [Calling best practices](https://docs.polymorfa.com/calls/best-practices)
- [Telemetry history](https://docs.polymorfa.com/api/bansafe/list-ban-safe-telemetry-history)
