> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymorfa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Telemetry and collection

> Inspect the bounded measurements behind BanSafe Health and check whether collection is fresh.

BanSafe telemetry contains bounded counts, booleans, enums, timing histograms,
and error-code counts from an eligible Linked Device session. It does not
contain message content, media, recipient identifiers, contact identifiers, or
chat history.

Open a number on **Safety** to see its collection status and browse recent
snapshots. Use these records to check what the estimator could measure at a
specific time. A measured zero is different from **Not measured**.

## Check collection status

`GET /platform/bansafe/collection?projectId={projectId}` lists collection status for
the numbers in a project. `GET /platform/bansafe/telemetry/{session}` returns the same
status with the latest supported snapshot for one number.

| State | Meaning |
| - | - |
| `fresh` | The latest supported record is no more than 10 minutes old. |
| `stale` | A supported record exists, but it is older than the freshness window. |
| `not_collected` | No retained record exists. This does not claim that collection is disabled. |
| `unsupported` | A retained record exists, but its version cannot be presented as a current measurement. |

Read `latestFlushedAt` as the time the number produced the record and
`latestReceivedAt` as the time Polymorfa stored it. `freshUntil` is the server's
freshness boundary. A partial record is a normal sub-hour snapshot; each signal
still states whether it was measured.

`droppedRecords` reports a gap declared by the collector. A value above zero
means the window is incomplete. It does not turn missing activity into a
measured zero.

## Browse signals

`GET /platform/bansafe/signals` returns the public signal catalogue. Each definition
has a stable `key`, a label and description, a group, a value kind, and a unit.

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

Each snapshot contains its bucket, flush, and receipt times, whether the bucket
was partial, the supported record version, and its `signals`.

| Signal field | Meaning |
| - | - |
| `measured` | Whether this record contains a usable observation for the signal |
| `value` | A number, boolean, enum value, or histogram bins; null when unmeasured or when `codes` carries the value |
| `sampleSize` | The number of observations behind a distribution or measurement, when applicable |
| `codes` | Bounded numeric error-code counts for a `code_counts` signal |

### Calls and new contacts

Two groups describe outreach on a Linked Device Number. Both carry 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` subset WhatsApp refused. `cold`, `warm`, and `unknown` split the callees by whether the Number had chatted with them; `heldByRestriction` counts calls Polymorfa refused while the Number was restricted; `inbound` counts calls the Number received. |
| `reach` | Distinct people with no prior chat reached in the bucket, by message (`newContactsByMessage`), by call (`newContactsByCall`), and in total (`newContacts`). `newContactsMax10m` is the highest number reached in any ten minutes of the bucket. |

A person counts once per UTC day, in the hour that first reached them, so
adding the hours of a day gives distinct people rather than repeated sends.
Unanswered and declined shares are these counts divided by `outbound`. The
cold-callee share is `cold` divided by `cold + warm + unknown`, which is its
own denominator: it counts calls that passed the restriction check and then
reached WhatsApp. A call that failed before reaching WhatsApp is in neither
the callee split nor `reach`, and a call placed while the check could not run
is not in the split. A Number reached by a runtime that
does not collect these groups reports them as unmeasured.

Do not infer a clean result from `measured: false`. Display it as unavailable
for that snapshot. Histograms contain aggregate bin counts, not event records.

## Authorization

All telemetry, collection, and Health-action inspection reads require
`sessions:read`. An
team credential supplies `projectId` for project lists. A project token
can read only its own project, and a conflicting project or number returns
`404`.

## Related

* [BanSafe Health](/guides/safety/overview)
* [Safety in Console](/console/safety)
* [Safety actions and restrictions](/guides/safety/enforcement)
* [Calls](/guides/calls/overview)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.