Tone docs
API referenceCampaigns

List a campaign's recipients and their outcomes

A recipient row names its LAST attempt. For every call the campaign placed, retries included, filter GET /v1/calls by campaign_id instead.

Open in ClaudeOpen in ChatGPTView as Markdown

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

GET
/v1/campaigns/{id}/recipients

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

Path Parameters

id*string

The campaign's id.

Query Parameters

limit?integer

How many results to return. 1-100, defaulting to 25.

Range1 <= value <= 100
Default25
cursor?string

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

Length1 <= length
status?string

Only recipients in this state. Open set — handle an unrecognised value rather than throwing. Today: pending, dialing, done, excluded, failed.

Value in

  • "pending"
  • "dialing"
  • "done"
  • "excluded"
  • "failed"
disposition?string

Only recipients whose LAST attempt ended this way. A recipient row names one attempt — for every call a campaign placed, retries included, filter GET /v1/calls by campaign_id instead. 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"
excluded_reason?string

Only recipients excluded at launch for this reason. Each excluded recipient is counted against exactly one reason. Open set — handle an unrecognised value rather than throwing. Today: invalid_number, duplicate, dnc, frequency_cap, dnd_scrub, blocked_by_gate.

Value in

  • "invalid_number"
  • "duplicate"
  • "dnc"
  • "frequency_cap"
  • "dnd_scrub"
  • "blocked_by_gate"
search?string

Substring match on the recipient number.

Length1 <= length <= 20

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/campaigns/string/recipients"
{  "data": [    {      "attemptCount": 0,      "costPaise": 0,      "createdAt": "2026-08-25T09:14:22Z",      "disposition": "answered",      "e164": "+919876543210",      "excludedReason": "invalid_number",      "id": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",      "lastCallId": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",      "nextAttemptAt": "2026-08-25T09:14:22Z",      "outcome": {},      "status": "running",      "talkSeconds": 0,      "variables": {}    }  ]}
Was this page helpful?

List campaigns, newest first (cursor-paginated)

Archived campaigns are hidden by default; pass archived=true to see only those. There is deliberately no way to ask for both at once.

Outcome tallies for the campaign funnel

Counts by disposition, plus the tallies of your declared output variables — how many said yes, how many rescheduled — which is usually the number the campaign existed to produce.