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 #
When enabled, API List 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 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.
This history may be incomplete when call updates cannot be saved. When retention deletion is enabled, the team's call retention period 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.
API
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"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) andhourreturn one group per day or hour intimezone, including empty ones. Adayrange covers at most 366 days and anhourrange at most 31 days.sessionreturns one group per Number, most calls first, up to 500 Numbers.groupsTruncatedistruewhen more Numbers had calls.outcomereturns 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.
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.
API
GET /platform/calls returns records newest first, up to 100 per page. Pass page.nextCursor as cursor, with the same filters, to read the next page.
curl "https://api.polymorfa.com/platform/calls?outcome=missed" \
-H "Authorization: Bearer $POLYMORFA_KEY"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 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:
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
doneimport { 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 and Control calls from your server. Another client sends them with API Report call diagnostics, 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>.
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'srateLimitrule. - Polymorfa accepts reports while the call is live and for 10 minutes after it ends. Later reports fail with
409, or410when 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
202but is not kept. - Polymorfa authorizes the call, not the connection: any participant your credential can act as can report for any
connectionIdon 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 #
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:
- Choose a Retention period: Short, Standard, Extended, Compliance or Custom.
- For Custom, enter a whole number of days from 1 to 2,555.
- 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:
curl https://api.polymorfa.com/platform/call-retention \
-H "Authorization: Bearer $POLYMORFA_TEAM_KEY"{
"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:
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 }'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: 0andupdatedAt: null.revisionincreases on every change. Send therevisionyou read asexpectedRevisionto refuse the update with409 state_conflictwhen someone changed the setting after you read it. - A named policy with a different
retentionDays, orcustomwithout one, fails with400 invalid_parameter. appliesTolists 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 and 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.
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.