Skip to content
Shortcut: /, ⌘K or Ctrl+K

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.

View as Markdown

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
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
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.

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:

OutcomeMeaning
answeredMedia connected. Answered calls still in progress count here
declinedA participant or the other party declined, or the line was busy
missedNobody answered before ringing stopped, or the caller hung up first
failedThe call ended before it connected for any other reason, such as a connection or capacity failure
in_progressThe call is still ringing

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

FilterValues
since, untilStart-time range. since is inclusive and until is exclusive
projectIdOne project
sessionIdOne Number, by its name
directioninbound or outbound
upstreamlinked_device or cloud_api: how the Number connects to WhatsApp
outcomeanswered, 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
curl "https://api.polymorfa.com/platform/calls?outcome=missed" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
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 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:

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
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 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>.

Shell
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 }.

FieldRule
kindquality or error
connectionIdThe 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 -
participantTeam keys and project tokens only. Client tokens omit it
clientOptional. 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)
qualityRequired for kind: "quality". Send at least one figure and omit the ones you did not measure
error.codeRequired for kind: "error". One of the codes below
FigureMeaningRange
rttMsRound-trip time in milliseconds0 to 60000
jitterMsReceive jitter in milliseconds0 to 60000
packetsLostPackets lost since the connection started0 to 2147483647
packetsReceivedPackets received since the connection started0 to 2147483647
audioCodecNegotiated audio codec, such as audio/opus1 to 32 characters from A-Z, a-z, 0-9, /, ., -
videoCodecNegotiated video codec, such as video/VP8Same as audioCodec
candidateTypeLocal ICE candidate type in use: host, srflx, prflx or relay (through a TURN relay)
reconnectsTimes the connection reconnected so far0 to 1000
Error codeMeaning
media_permission_deniedThe user or browser denied microphone or camera access
device_not_foundNo microphone or camera was found
device_in_useAnother application was using the microphone or camera
ice_failedThe media connection could not be established or was lost
negotiation_failedSDP negotiation failed
media_timeoutMedia stopped arriving
reconnect_exhaustedThe app stopped trying to reconnect
token_refresh_failedThe app could not get a new client token
unsupported_browserThe browser does not support calls
otherAny 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 #

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.
PolicyPeriod
short7 days
standard30 days
extended (default)90 days
compliance365 days
custom1 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:

Shell
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:

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
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 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.

See also#