REST API: voice calls

Use GET /voice/calls to list voice calls handled by your agents, for reporting or for building your own call history view. Use GET /voice/calls/{id}/recording-url to fetch a playback URL for a specific call's recording.

The voiceProvider field is how the call was billed, not the name of one engine. It holds one of three values: a realtime engine id, such as gpt-realtime-1.5; the id of a voice-combination chain, such as deep-reasoning; or the literal combination:custom for a chain that no named chain matches. A call that ran a combination therefore reports a value that is not an engine id. Do not treat this field as an engine id, and do not build a fixed list of the values it can hold. The three models of a combination are not returned by this endpoint. See Configure voice calls for the providers.

The recording URL is short-lived. Fetch it just before you need to play or download the recording, not ahead of time, and request a fresh URL if enough time has passed that the previous one may have expired. Do not store the URL itself as a durable reference to the recording; store the call identifier and request a new URL when you need access again.

Call recordings can contain sensitive customer conversations. Restrict which of your own systems and users can call this endpoint, and apply the same handling standards to a fetched recording that you apply to any other customer voice data, including retention and deletion practices consistent with your organization's policies.

These endpoints are read-only. Configuring voice channels, phone numbers, and call handling remains a dashboard task.

PagingCopy Anchor Link

GET /voice/calls returns calls newest first, one page at a time. limit sets the page size, from 1 to 200, and defaults to 100. The response is { calls, nextCursor, hasMore }. When hasMore is true, more calls match your filters than this page holds: pass nextCursor back as after, with the same filters, to fetch the next page. On the last page hasMore is false and nextCursor is null. Calls that share a start time are ordered by id, so a page boundary never skips or repeats one. An after whose call no longer exists, or belongs to another organization, returns an empty page.

ChangesCopy Anchor Link

• 2026-10-17 — GET /voice/calls returns nextCursor and hasMore beside calls, and takes an after cursor. Before this change, a caller with more calls than limit got the first page and no sign that more existed. calls, limit, and its default of 100 are unchanged.