# Call records and retention

> Read call statistics and call detail records, report call diagnostics from your app, and choose how long call data is kept.

Polymorfa records every call on your Numbers: who answered, how it ended, how
long it lasted and how its media performed. Read the history in the Console or
through the Platform API, add the quality figures your app measures, and choose
how long the data is kept.

Polymorfa does not record call audio or video. Platform call records identify
the other party with `peerRef`. The Number call-history capability described
below can store the other party's identity; it is not yet available.

## A Number's call history

> **Note**
>
> Number call history with peer identity is not yet released. Its endpoint and
> client-token access require matching API support. Use the Platform call
> records below until this capability is available.

When enabled, `GET /messaging/{session}/calls` lists one Number's calls,
newest first. Its `peer` field can include the other party's user ID, phone
number and username, as the call reported them. `peer` can be null, and each
identity field can be absent. These records are stored and served in the
Number's data region. Enabling the capability does not backfill older calls.

The request accepts a team key or project token with `sessions:read`, or a
[client token](https://docs.polymorfa.com/development/client-tokens) with
`read_calls` in both its ceiling and the Number's live rules. A project token
can read only its own project. No configured history source, or no available
Number placement, returns `503`; the API does not substitute another region.

Filter by `direction`, `outcome`, `since` and `until`. `limit` is 1 to 100
(default 25). Pass a non-null `nextCursor` as `cursor` with the same filters
for the next page. See [List a Number's calls](https://docs.polymorfa.com/api/calls/list-session-calls).

This history may be incomplete when call updates cannot be saved. When
retention deletion is enabled, the team's [call retention period](#call-data-retention)
also applies to these records. An unfinished record becomes eligible for
deletion seven days after its normal cutoff, even if no final update arrives.
Changing a period alone does not enable deletion.

## Read call statistics

**Console:**

Open **Calls** in a project, or choose **All projects**. The call summary below
the calls table shows the number of calls, answered, missed, declined and
failed calls, the answer rate, total talk time and the average call length,
with charts by day or hour and a heatmap by weekday and hour. See
[Calls in the Console](https://docs.polymorfa.com/calls/console#call-summary).

**API:**

```bash cURL
curl "https://api.polymorfa.com/platform/calls/stats?since=2026-09-01T00:00:00Z&until=2026-09-08T00:00:00Z&groupBy=day&timezone=America/Sao_Paulo" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
const { data: stats } = await platform.calls.stats({
  since: "2026-09-01T00:00:00Z",
  until: "2026-09-08T00:00:00Z",
  groupBy: "day",
  timezone: "America/Sao_Paulo",
});

console.log(stats.totals.answerRate, stats.groups.length);
```

Without `since` and `until`, the range is the last 7 days. `groupBy` selects
the groups:

- `day` (the default) and `hour` return one group per day or hour in
  `timezone`, including empty ones. A `day` range covers at most 366 days and
  an `hour` range at most 31 days.
- `session` returns one group per Number, most calls first, up to 500 Numbers.
  `groupsTruncated` is `true` when more Numbers had calls.
- `outcome` returns one group per outcome.

`timezone` takes an IANA name such as `UTC`, `CET` or `Europe/Lisbon`, in any
case; the response's `timezone` is the canonical name. UTC offsets and POSIX
strings such as `UTC+3` are refused. Hour groups are local clock hours: on the
day a zone moves its clocks, the skipped hour has no group and the repeated
hour is one group. Every group and the `totals` report `calls`, the count for
each outcome, `answerRate`, `totalDurationSeconds` and `averageDurationSeconds`.
`heatmap` always has 168 cells, one per day of week (`1` is Monday) and hour,
in `timezone`. See [Get call stats](https://docs.polymorfa.com/api/calls/get-call-stats).

*TypeScript:*

`calls` on a team client covers every project unless you pass `projectId`; on
a project client it reads only that project. `since` and `until` also accept
`Date` objects.

`answerRate` is answered calls divided by calls that are no longer ringing.
Durations count connected time only.

## Outcomes and filters

Each call has one outcome:

| Outcome | Meaning |
| --- | --- |
| `answered` | Media connected. Answered calls still in progress count here |
| `declined` | A participant or the other party declined, or the line was busy |
| `missed` | Nobody answered before ringing stopped, or the caller hung up first |
| `failed` | The call ended before it connected for any other reason, such as a connection or capacity failure |
| `in_progress` | The call is still ringing |

The statistics, list and export endpoints accept the same filters:

| Filter | Values |
| --- | --- |
| `since`, `until` | Start-time range. `since` is inclusive and `until` is exclusive |
| `projectId` | One project |
| `sessionId` | One Number, by its name |
| `direction` | `inbound` or `outbound` |
| `upstream` | `linked_device` or `cloud_api`: how the Number connects to WhatsApp |
| `outcome` | `answered`, `missed`, `declined`, `failed` or `in_progress` |

They accept a team key or a project token with `sessions:read`. A project token
reads only its own project; a team key reads the whole team unless you pass
`projectId`.

## List and export call detail records

**Console:**

The **Calls** table lists each call's party, Number, state, connection,
duration and start time. Select a call for its participants, connections,
quality figures and webhook deliveries. See
[Calls in the Console](https://docs.polymorfa.com/calls/console#find-a-call).

**API:**

[`GET /platform/calls`](https://docs.polymorfa.com/api/calls/list-call-records) returns
records newest first, up to 100 per page. Pass `page.nextCursor` as `cursor`,
with the same filters, to read the next page.

```bash cURL
curl "https://api.polymorfa.com/platform/calls?outcome=missed" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
for await (const call of await platform.calls.list({ outcome: "missed" })) {
  console.log(call.callId, call.sessionId, call.direction, call.peerRef);
}

const detail = await platform.calls.retrieve("<call-id>");
console.log(detail.data.history.events);
```

*TypeScript:*

`calls.list` returns a page you can loop over; the SDK fetches the next pages.
`calls.retrieve` returns one call's full detail, including its event history
and media measurements.

[`GET /platform/calls/export`](https://docs.polymorfa.com/api/calls/export-call-records)
returns the same records as CSV (`format=csv`, the default) or newline-delimited
JSON (`format=ndjson`), up to 1,000 per request. Each CSV page starts with a
header row. When more records match, the `Polymorfa-Next-Cursor` response
header holds the cursor for the next page:

```bash cURL
cursor=""
while :; do
  curl -sS -D headers.txt "https://api.polymorfa.com/platform/calls/export?format=ndjson&since=2026-09-01T00:00:00Z${cursor:+&cursor=$cursor}" \
    -H "Authorization: Bearer $POLYMORFA_KEY" >> calls.ndjson
  cursor=$(grep -i '^polymorfa-next-cursor:' headers.txt | cut -d' ' -f2 | tr -d '\r')
  [ -n "$cursor" ] || break
done
```

```typescript TypeScript
import { createWriteStream } from "node:fs";

const file = createWriteStream("calls.ndjson");
for await (const chunk of platform.calls.exportAll({ format: "ndjson", since: "2026-09-01T00:00:00Z" })) {
  file.write(chunk);
}
file.end();
```

*TypeScript:*

`calls.exportAll` returns every export page as text, in order. CSV pages after
the first leave out the header row, so you can write the chunks to one file.
`calls.export` returns a single page of up to 1,000 records with a
`nextCursor`.

In CSV, a text value that starts with `=`, `+`, `-`, `@`, a tab or a carriage
return is prefixed with an apostrophe so spreadsheets do not run it as a
formula.

Each record has `callId`, `projectId`, `sessionId`, `direction`, `upstream`,
`outcome`, `state`, `hasVideo`, `peerRef`, `startedAt`, `connectedAt`,
`endedAt`, `durationSeconds` and `endReason`. `peerRef` is the other party's
team-specific pseudonym: the same person has the same `peerRef` across your
team's calls, but it is not a phone number and Polymorfa cannot turn it back
into one.

A call keeps its original project after its Number is deleted. Reusing the
Number's name in another project does not transfer its history, statistics or
usage. Records whose original project is unknown have `projectId: null` and
appear only in team-wide reads.

Call history can lag behind live events during a temporary recording failure.
Failed writes are retried for up to 24 hours. A delayed event does not move an
accepted or finished call back to ringing.

## Report call diagnostics from your app

Your app can send the quality figures and errors it measures on each of its
connections. The Console shows them on the call's details, next to the
measurements of Polymorfa's media service. Reports are optional; a call without
them works the same.

The browser client and `@polymorfa/sdk/calls` send reports by default; see
[Add calling to a web app](https://docs.polymorfa.com/calls/web#diagnostics) and
[Control calls from your server](https://docs.polymorfa.com/calls/server#speak-and-listen-on-a-call).
Another client sends them with `POST /messaging/voip/calls/{id}/reports`, using
the credential that carries the call: a client token needs the `voip_signal`
action, and a team key or project token reports as `server:<participant>`.

```bash
curl -X POST "https://api.polymorfa.com/messaging/voip/calls/CALL_ID/reports" \
  -H "Authorization: Bearer $POLYMORFA_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "quality",
    "connectionId": "conn_0123456789",
    "client": { "sdk": "my-call-app", "version": "2.3.0", "platform": "browser" },
    "quality": {
      "rttMs": 84,
      "jitterMs": 6,
      "packetsLost": 12,
      "packetsReceived": 4810,
      "audioCodec": "audio/opus",
      "candidateType": "relay",
      "reconnects": 0
    }
  }'
```

A successful report returns `202` with `{ "success": true }`.

| Field | Rule |
| --- | --- |
| `kind` | `quality` or `error` |
| `connectionId` | The ID your app chose for the connection, as `call.connection_joined` reports it. 8 to 64 characters from `A-Z`, `a-z`, `0-9`, `_` and `-` |
| `participant` | Team keys and project tokens only. Client tokens omit it |
| `client` | Optional. `sdk` (1 to 32 characters from `a-z`, `0-9`, `@`, `/`, `.`, `_`, `-`), `version` (`MAJOR.MINOR.PATCH` with an optional suffix, at most 32 characters) and `platform` (`browser`, `node` or `other`) |
| `quality` | Required for `kind: "quality"`. Send at least one figure and omit the ones you did not measure |
| `error.code` | Required for `kind: "error"`. One of the codes below |

| Figure | Meaning | Range |
| --- | --- | --- |
| `rttMs` | Round-trip time in milliseconds | 0 to 60000 |
| `jitterMs` | Receive jitter in milliseconds | 0 to 60000 |
| `packetsLost` | Packets lost since the connection started | 0 to 2147483647 |
| `packetsReceived` | Packets received since the connection started | 0 to 2147483647 |
| `audioCodec` | Negotiated audio codec, such as `audio/opus` | 1 to 32 characters from `A-Z`, `a-z`, `0-9`, `/`, `.`, `-` |
| `videoCodec` | Negotiated video codec, such as `video/VP8` | Same as `audioCodec` |
| `candidateType` | Local ICE candidate type in use: `host`, `srflx`, `prflx` or `relay` (through a TURN relay) | |
| `reconnects` | Times the connection reconnected so far | 0 to 1000 |

| Error code | Meaning |
| --- | --- |
| `media_permission_denied` | The user or browser denied microphone or camera access |
| `device_not_found` | No microphone or camera was found |
| `device_in_use` | Another application was using the microphone or camera |
| `ice_failed` | The media connection could not be established or was lost |
| `negotiation_failed` | SDP negotiation failed |
| `media_timeout` | Media stopped arriving |
| `reconnect_exhausted` | The app stopped trying to reconnect |
| `token_refresh_failed` | The app could not get a new client token |
| `unsupported_browser` | The browser does not support calls |
| `other` | Any other error |

Reports accept only these fields. Polymorfa does not accept error messages,
device names, IP addresses, SDP or user agents in a report; a request that
contains them fails with `400`.

- Each connection can send one quality report every 5 seconds and 20 error
  reports per minute. More fail with `429`. Reports also count toward a client
  token's `rateLimit` rule.
- Polymorfa accepts reports while the call is live and for 10 minutes after it
  ends. Later reports fail with `409`, or `410` when the call ended because its
  media host was lost.
- Polymorfa keeps up to 200 reports per call. At that limit, a quality report
  replaces the same connection's oldest quality report. A quality report from a
  connection with no stored quality report, and every error report, returns
  `202` but is not kept.
- Polymorfa authorizes the call, not the connection: any participant your
  credential can act as can report for any `connectionId` on a call that
  credential can reach.

A cadence that keeps the Console current: a quality report every 15 seconds
during the call and one when the connection closes, and an error report when an
error occurs.

## Choose how long call data is kept

> **Note**
>
> Deletion starts on a date announced in the [changelog](https://docs.polymorfa.com/changelog) before it
> begins. Until then, choosing a period records your choice and deletes nothing.

Your team chooses how long Polymorfa keeps its call data. Once deletion starts,
Polymorfa deletes call data older than that period from every project in the
team:

- call records: the call history the Console and API list;
- call events: each call's participant and connection history;
- the diagnostics your apps report for their call connections.

| Policy | Period |
| --- | --- |
| `short` | 7 days |
| `standard` | 30 days |
| `extended` (default) | 90 days |
| `compliance` | 365 days |
| `custom` | 1 to 2,555 days that you set |

**Console:**

The **Call data retention** card at the bottom of the **Calls** page shows the
period. Team owners and admins change it:

1. Choose a **Retention period**: Short, Standard, Extended, Compliance or
   Custom.
2. For **Custom**, enter a whole number of days from 1 to 2,555.
3. Select **Save retention**. A shorter period asks you to confirm first.

**API:**

Read the setting with any team key or project token that has `sessions:read`:

```bash
curl https://api.polymorfa.com/platform/call-retention \
  -H "Authorization: Bearer $POLYMORFA_TEAM_KEY"
```

```json
{
  "success": true,
  "data": {
    "policy": "extended",
    "retentionDays": 90,
    "appliesTo": ["call_records", "call_events", "client_reports"],
    "revision": 0,
    "updatedAt": null
  }
}
```

Change it with a team key that has `sessions:manage`. Send `retentionDays` only
with the `custom` policy:

```bash cURL
curl -X PUT https://api.polymorfa.com/platform/call-retention \
  -H "Authorization: Bearer $POLYMORFA_TEAM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "policy": "custom", "retentionDays": 180, "expectedRevision": 0 }'
```

```typescript TypeScript
const { data: current } = await platform.callRetention.retrieve();
console.log(current.policy, current.retentionDays);

await platform.callRetention.update({
  policy: "custom",
  retentionDays: 180,
  expectedRevision: current.revision,
});
```

*TypeScript:*

Retention is one setting for the whole team, so use a team client with a team
key. A stale `expectedRevision` throws `PolymorfaConflictError` with
`state_conflict`. Without it, the update applies regardless of other changes.

- Project tokens can read the setting but not change it; a change fails with
  `403`. Client tokens can do neither.
- A team without a saved setting returns `revision: 0` and `updatedAt: null`.
  `revision` increases on every change. Send the `revision` you read as
  `expectedRevision` to refuse the update with `409 state_conflict` when
  someone changed the setting after you read it.
- A named policy with a different `retentionDays`, or `custom` without one,
  fails with `400 invalid_parameter`.
- `appliesTo` lists the kinds of call data the period covers. When Polymorfa
  stores a new kind of call data, it is added to this list and follows the
  same period.

See [Get call retention](https://docs.polymorfa.com/api/calls/get-call-retention) and
[Update call retention](https://docs.polymorfa.com/api/calls/update-call-retention).

Once deletion runs, Polymorfa deletes call data within 24 hours after it
becomes older than the period. A large backlog, such as the call data already
stored when deletion starts or when you shorten the period, can take longer to
delete. A call is measured from when it started; a call that is still ringing
or in progress is kept until it ends.

> **Warning**
>
> **A shorter period deletes stored data.** Once deletion runs, data older than
> the new period is deleted within 24 hours and cannot be recovered. A longer
> period does not restore data that was already deleted.

Reports are deleted with the call's history when they pass the retention
period. Deleting a team removes access to its history; it does not guarantee
immediate erasure of retained records.

## See also

- [Calls in the Console](https://docs.polymorfa.com/calls/console)
- [How calls work](https://docs.polymorfa.com/calls/how-calls-work)
