Tone docs
API referenceCalls

List calls, newest first (cursor-paginated)

Every call, inbound and outbound, including campaign calls. Filter by agent, number, campaign, direction, disposition or date range. A campaign filter here returns every ATTEMPT including retries, which the recipient list cannot give you.

Open in ClaudeOpen in ChatGPTView as Markdown

Requires the read scope. A key with less gets 403 insufficient_scope.

GET
/v1/calls

Authorization

AuthorizationBearer <token>

Authorization: Bearer tone_live_… or tone_test_…. The prefix IS the environment: a test key reaches only the sandbox, and no request field bridges the two.

In: header

Query Parameters

limit?integer

How many calls to return. 1-100.

Range1 <= value <= 100
Default25
cursor?string

Opaque page cursor — pass meta.pagination.cursor from the previous response. Its contents are an implementation detail; do not parse or construct one.

Length1 <= length
agent_id?string

Only calls run by this agent, across every one of its versions.

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
number_id?string

Only calls placed from, or received on, this number.

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
campaign_id?string

Every call this campaign placed, retries included — which is what the recipient list cannot give you, since a recipient row names only its LAST attempt.

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
direction?string

Which way the call went. Open set — handle an unrecognised value rather than throwing. Today: inbound, outbound.

Value in

  • "inbound"
  • "outbound"
channel?string

How the call was carried. browser is the in-dashboard microphone test only; every dial the API places is pstn. Open set — handle an unrecognised value rather than throwing. Today: browser, pstn.

Value in

  • "browser"
  • "pstn"
status?string

Where the call is in its lifecycle. Open set — handle an unrecognised value rather than throwing. Today: queued, in_progress, ended.

Value in

  • "queued"
  • "in_progress"
  • "ended"
disposition?string

How the call finished. Only set once status is ended. Open set — handle an unrecognised value rather than throwing. Today: answered, no_answer, busy, failed, voicemail, unknown.

Value in

  • "answered"
  • "no_answer"
  • "busy"
  • "failed"
  • "voicemail"
  • "unknown"
environment?string

Ignored when you authenticate with an API key: the key's own prefix pins the environment, so a tone_test_ key structurally cannot read live calls.

Value in

  • "live"
  • "test"
from?string

Inclusive lower bound on createdAt. A bare date (2026-08-01) is accepted and read as midnight UTC.

to?string

Exclusive upper bound on createdAt. Must be later than from.

include_unstarted?string

Include rows for calls that never started — an abandoned browser test dialog mints one, so they are hidden by default.

Value in

  • "0"
  • "1"
  • "true"
  • "false"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/calls"
{  "data": [    {      "agent": {        "id": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",        "name": "Order confirmation"      },      "agentVersion": 3,      "billedPaise": 600,      "campaignId": null,      "channel": "pstn",      "compliance": "passed",      "createdAt": "2026-08-25T09:14:22Z",      "direction": "outbound",      "disposition": "answered",      "durationSeconds": 45,      "endReason": "agent_ended",      "endedAt": "2026-08-25T09:15:11Z",      "environment": "live",      "evaluations": {},      "hasRecording": true,      "hasTranscript": true,      "id": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",      "initiator": {        "id": "key_8f14a2c9",        "type": "api_key"      },      "number": {        "e164": "+918045678901",        "id": "4b7c1a02-9de5-4f31-bb07-2c1a5e9f0d43"      },      "outputs": {        "confirmed": true,        "delivery_day": "Thursday"      },      "peer": "+919876543210",      "quality": {        "answerP50Ms": 480,        "perceivedP50Ms": 0,        "turns": 6      },      "ratePaisePerMinute": 600,      "startedAt": "2026-08-25T09:14:26Z",      "status": "ended",      "summary": "Customer confirmed the order and asked for Thursday delivery.",      "variables": {        "customer_name": "Priya",        "order_id": "AC-4417"      },      "verdict": "success"    }  ]}
Was this page helpful?

Fetch a single call

The full call detail record: outcome, duration, what was billed, the agent version that ran it, your declared output variables, the evaluation verdicts and the per-call variables it was given.

Fetch a call's audio recording (WAV)

Streams the recording as audio/wav, in stereo: the caller on the left channel, the agent on the right. Not enveloped, and often several megabytes. Absent when recording is off for the number, or when the call never connected.