Audatec Voice AI

An AI Call Platform that gives your application a real voice. Trigger AI-powered outbound calls at scale — outcomes delivered instantly.

How it works

Every call flows through three components:

• Agents — an AI persona with a script, voice, and expected input fields (e.g. customer_name, amount_due)
• SIP Trunks — carrier lines with concurrency limits assigned to your org
• Calls — a request that combines a phone number, an agent, a trunk, and per-call metadata

Base URL

https://api.audatec.in/integration/v1

Authentication

Every request to the API must include an API key in the Authorization header.

API Key Format

Using your key

Include your key in the Authorization header on every request:

Authorization: Bearer audtk_your_key_here

Getting a key

Generate API keys from the Audatec Dashboard:

1. Log in to studio.audatec.in
2. Navigate to Settings → Integration
3. Click New API Key, give it a name, and select a role
4. Copy the key immediately — it is shown only once

Key roles

Each key carries a role that controls what it can do:

A request outside the key's role is refused with 403 and "code": "insufficient_scope".

Keys are org-scoped — a key authenticates as the organisation, not an individual user. All agents and trunks belonging to your org are accessible with a valid key. You can also send the key as an X-Client-Key header instead of Authorization.

Quick Start

Place your first AI call in three steps.

curl https://api.audatec.in/integration/v1/agents \
  -H "Authorization: Bearer $API_KEY"

curl https://api.audatec.in/integration/v1/sip-trunks \
  -H "Authorization: Bearer $API_KEY"

curl -X POST https://api.audatec.in/integration/v1/calls \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+919876543210",
    "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
    "sip_trunk_id": "d5f3a1c0-8b2e-4f9a-b7d1-1e2c3a4b5c6d",
    "metadata": {
      "customer_name": "Rahul Sharma",
      "amount_due": "7500",
      "due_date": "2026-06-20"
    }
  }'

List Agents

Returns the active AI agents available to your organisation, including the metadata fields each agent requires.

Response — 200 OK

{
  "agents": [
    {
      "id": "830f767a-397e-4b39-82ff-235cd344e2f9",
      "name": "EMI Reminder Agent",
      "status": "active",
      "has_live_version": true,
      "input_schema": {
        "fields": ["customer_name", "amount_due", "due_date"],
        "sample_context": {
          "customer_name": "Rahul Sharma",
          "amount_due": "7500",
          "due_date": "2026-06-20"
        }
      }
    }
  ]
}

Response fields

List SIP Trunks

Returns the active SIP trunks (carrier lines) your organisation has been allocated, with your concurrency and rate limits on each.

Response — 200 OK

{
  "sip_trunks": [
    {
      "id": "d5f3a1c0-8b2e-4f9a-b7d1-1e2c3a4b5c6d",
      "provider_trunk_id": "ST_xxxxxxxxxxxx",
      "trunk_phone_number": "+918069XXXXXX",
      "max_cps": 5,
      "max_channels": 100,
      "status": "active"
    }
  ]
}

Response fields

Trigger a Call

Dispatch a single outbound AI call. The call is accepted immediately and your agent starts the conversation when the recipient answers. Calls are never queued: if your trunk allocation is full you get a 429 and should retry.

Requires a key with the member role or higher. A viewer key (or a results-only key) gets 403.

Request headers

Request body

Example request

{
  "phone_number": "+919876543210",
  "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
  "sip_trunk_id": "d5f3a1c0-8b2e-4f9a-b7d1-1e2c3a4b5c6d",
  "metadata": {
    "customer_name": "Rahul Sharma",
    "amount_due": "7500",
    "due_date": "2026-06-20"
  }
}

Responses

{
  "call_id": "31106b7c-9d02-4723-8b07-5bb8d90240cb",
  "status": "triggered",
  "poll_url": "/integration/v1/calls/31106b7c-9d02-4723-8b07-5bb8d90240cb/status"
}

{
  "call_id": "31106b7c-9d02-4723-8b07-5bb8d90240cb",
  "status": "duplicate",
  "poll_url": "/integration/v1/calls/31106b7c-9d02-4723-8b07-5bb8d90240cb/status"
}

{
  "error": "Trunk concurrency (max_channels) exhausted",
  "call_id": "31106b7c-9d02-4723-8b07-5bb8d90240cb",
  "status": "rejected"
}

{
  "error": "Dialer unavailable",
  "call_id": "31106b7c-9d02-4723-8b07-5bb8d90240cb",
  "status": "failed"
}

400 / 404 return { "error": "..." } — see Error Handling for the messages.

Retrying safely

If a request times out you cannot tell whether the call was placed. Send an Idempotency-Key and retry with the same key: you get the original call_id back (200, "status": "duplicate") and the customer is not called twice.

• Use one key per intended call — for example built from your own record, like loan-84213-reminder-2026-06-20 — and reuse it on every retry of that call.
• A new call to the same customer (tomorrow's reminder) needs a new key.
• Keys are scoped to your API key.
• Send retries one after another, not simultaneously.

Get Call Status

Returns the current state and outcome of a call. Poll this endpoint until is_terminal is true.

Path parameters

Response — 200 OK

{
  "id": "31106b7c-9d02-4723-8b07-5bb8d90240cb",
  "phone_number": "+919876543210",
  "status": "ended",
  "outcome": "connected",
  "is_terminal": true,
  "disposition": "PROMISE_TO_PAY",
  "duration_secs": 97,
  "started_at": "2026-06-14T10:32:05.000Z",
  "ended_at": "2026-06-14T10:33:42.000Z",
  "transcript_url": "https://[bucket-id].s3.ap-south-1.amazonaws.com/[resource-id]",
  "recording_url": "https://[bucket-id].s3.ap-south-1.amazonaws.com/[resource-id]"
}

Response fields

Returns 404 if the call does not exist or belongs to another organisation. Requires a key that can read calls (viewer role or higher, with the calls scope).

Results Access

How access to campaign results works: what a key can read, how to get one, and the limits that apply.

The results key

Campaign results are read with a results key, an API key that holds the results:read scope. It is sent like any other key, as Authorization: Bearer audtk_…, and works only on the results endpoints: Campaigns & Runs, Get Results and Get Summary. On any other endpoint, such as POST /calls, it returns 403 with "code": "insufficient_scope". The scope is held by the viewer role and up.

Which campaigns a key can see

Anyone in your organisation who can create API keys can create a results key and read all of the organisation's campaign results with it, so keep keys as private as the data itself.

• A results key belongs to your organisation. It reads the results of every campaign in that organisation, and never of any other organisation.
• GET /campaigns lists your organisation's campaigns (paged).
• A campaign that does not exist, was deleted, or belongs to another organisation returns the same 404 ("Campaign not found"), so a key cannot discover other organisations' campaigns.
• A run that is not part of the campaign you ask about returns 404 ("Run not found").

Which fields a key can see

The fields are fixed by Audatec for each campaign, according to the campaign's agent. Each campaign's result_schema (in Get Campaign) lists their names, types and meanings. Nothing else is ever returned: no raw call data, no costs, and no columns from your uploaded contact file other than the input variables your agent is declared to take (returned as metadata, below). (The transcript and recording links are included, for connected calls only.) A campaign whose agent has no dedicated field set returns the common fields only. If you need another field, ask Audatec to add it.

Getting a key

Create a key under Settings → Integration in the Audatec Voice Platform (organisation admins), or ask Audatec to issue one with the results scope. The key is shown once, so store it securely. Regenerate replaces a key with a new secret that keeps the same name, role and scopes, and revokes the old one at once. If a key is lost or exposed, revoke it.

Limits

To protect the service and your data, each results key has limits: 250 rows per page, 60 requests a minute, and 500,000 result rows a day (resets at 00:00 UTC). Results are always read one run at a time. See Rate Limits & Paging for the details, the error responses and how to read results politely.

Campaigns & Runs

Read the campaigns you have been given access to, the fields their results contain, and their runs. Read-only.

Your organisation's campaigns, newest first. Paged: limit (1–200, default 100) and cursor (the previous response's pagination.next_cursor).

{
  "campaigns": [
    {
      "id": "0b7c9a52-6f0e-4c3d-9a7e-2f6d1c8e4b10",
      "name": "Gold Loan — Pre-Auction Reminder",
      "status": "active",
      "created_at": "2026-08-01T05:30:00.000Z",
      "last_run_at": "2026-09-29T09:10:00.000Z"
    }
  ],
  "pagination": { "limit": 100, "has_more": false, "next_cursor": null }
}

One campaign, plus result_schema — the complete list of fields (name, type, description) that its result rows contain, and metadata_fields, the names of the input variables returned in each row's metadata. This is the contract for the results of that campaign; it works like input_schema on List Agents. result_schema.version changes only when fields change.

{
  "id": "0b7c9a52-6f0e-4c3d-9a7e-2f6d1c8e4b10",
  "name": "Gold Loan — Pre-Auction Reminder",
  "status": "active",
  "created_at": "2026-08-01T05:30:00.000Z",
  "last_run_at": "2026-09-29T09:10:00.000Z",
  "result_schema": {
    "version": "iifl_gl_v1",
    "description": "IIFL Gold Loan pre-auction reminder",
    "fields": [
      { "name": "phone_number", "type": "string", "description": "The contact's phone number." },
      { "name": "disposition", "type": "string|null", "description": "The agent's classification of the conversation." },
      { "name": "metadata", "type": "object", "description": "The call's input variables (what the agent was given), by variable name; see metadata_fields." },
      { "name": "promise_to_pay", "type": "boolean|null", "description": "The customer promised to pay." }
    ],
    "metadata_fields": ["callee_name", "dpd", "total_os_bucket", "min_amount_to_stop_auction", "branch_name"]
  }
}

The campaign's runs, newest first — every run, whatever its status (completed, cancelled, failed, …). A run is one attempt of a batch. Results are always read for one run, so use a run's id as the run_id of Get Results and Get Summary. Paged: limit (1–200, default 100) and cursor (the previous response's pagination.next_cursor). To see only the runs of a time period, add from and/or to (ISO 8601; from inclusive, to exclusive; a bare date such as 2026-09-05 means 00:00 UTC). A run belongs to a period by the time it was created. The response repeats the period you asked for as "period": { "from": …, "to": … } (null for an open end).

{
  "period": { "from": "2026-09-01T00:00:00.000Z", "to": "2026-10-01T00:00:00.000Z" },
  "runs": [
    {
      "id": "9f1d2e3c-4b5a-4c6d-8e7f-0a1b2c3d4e5f",
      "attempt_no": 2,
      "previous_run_id": "3c7e1b90-5d2a-4f18-a6b4-91e0d8c2f4a7",
      "status": "completed",
      "total_rows": 1583,
      "processed_rows": 1583,
      "success_rows": 940,
      "failed_rows": 643,
      "scheduled_at": null,
      "started_at": "2026-09-29T09:10:00.000Z",
      "completed_at": "2026-09-29T11:42:00.000Z"
    }
  ],
  "pagination": { "limit": 100, "has_more": false, "next_cursor": null }
}

Get Results

One row per contact in one run, showing the contact's final outcome in that run. Paged and filterable, so a dashboard can stay in sync cheaply.

Query parameters

Response — 200 OK

{
  "run": { "id": "9f1d2e3c-4b5a-4c6d-8e7f-0a1b2c3d4e5f", "attempt_no": 2, "previous_run_id": "3c7e1b90-5d2a-4f18-a6b4-91e0d8c2f4a7" },
  "period": { "from": null, "to": null },
  "results": [
    {
      "phone_number": "+919876543210",
      "run_id": "9f1d2e3c-4b5a-4c6d-8e7f-0a1b2c3d4e5f",
      "status": "ended",
      "outcome": "connected",
      "is_terminal": true,
      "disposition": "PROMISE_TO_PAY",
      "duration_secs": 97,
      "transcript_url": "https://[bucket-id].s3.ap-south-1.amazonaws.com/[transcript-id]",
      "recording_url": "https://[bucket-id].s3.ap-south-1.amazonaws.com/[recording-id]",
      "attempts_made": 2,
      "first_attempted_at": "2026-09-28T09:11:00.000Z",
      "last_attempted_at": "2026-09-29T09:14:00.000Z",
      "updated_at": "2026-09-29T09:15:40.000Z",
      "metadata": {
        "callee_name": "Rahul Kumar",
        "dpd": "92",
        "total_os_bucket": "1750155.76",
        "min_amount_to_stop_auction": "21955.7",
        "branch_name": "Connaught Place"
      },
      "promise_to_pay": true,
      "payment_timeline": "Friday"
    }
  ],
  "pagination": { "limit": 100, "has_more": true, "next_cursor": "eyJwIjoiKzkxOTg3NjU0MzIxMCJ9" }
}

run says which run the rows belong to (previous_run_id is null unless it is a smart-retry pass). Rows are ordered by phone_number. The fields in each row are exactly those listed in the campaign's result_schema; the example above shows the common fields plus a few campaign-specific ones. A field with no value is null.

Common fields

What "final outcome" means

The row shown is the contact's result within this run: the call where they connected, if they did; otherwise their most recent call in the run. attempts_made counts the calls made to them in this run. A contact retried in a later pass (a run with previous_run_id) has a separate row, with its own result, in that later run — read each run you want.

Keeping a dashboard in sync

Don't re-read every row on each refresh. Per run, store the largest updated_at you have seen, and next time ask only for rows changed since then. Each contact appears once per run, so overwrite by phone_number within that run. Runs that have completed rarely change; keep refreshing only the ones still in progress.

let since = loadCheckpoint(RUN_ID);      // ISO timestamp, or null the first time for this run
let cursor = null, newest = since;

do {
  const url = new URL(`${BASE}/campaigns/${CAMPAIGN_ID}/results`);
  url.searchParams.set('run_id', RUN_ID);
  url.searchParams.set('limit', '500');
  if (since) url.searchParams.set('updated_since', since);
  if (cursor) url.searchParams.set('cursor', cursor);

  const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
  const { results, pagination } = await res.json();

  for (const row of results) {
    upsertByPhone(row);                  // one row per phone_number: overwrite what you have
    if (!newest || row.updated_at > newest) newest = row.updated_at;
  }
  cursor = pagination.has_more ? pagination.next_cursor : null;
} while (cursor);

saveCheckpoint(RUN_ID, newest);          // next time: updated_since = newest

Usage limits

Results are meant to be read in small pages and, after the first read, incrementally. Each results key is limited to:

• 60 requests a minute across all the results endpoints (X-RateLimit-Limit and X-RateLimit-Remaining are returned on every response);
• 500,000 result rows a day on /results (resets at 00:00 UTC; X-Daily-Rows-Remaining shows what is left);
• 250 rows per page, and a query that runs longer than about 20 seconds is stopped.

Over a limit you receive 429 with a Retry-After header (seconds) and a code of rate_limited or daily_quota_exceeded. Use updated_since to fetch only what changed, and read a finished run once. See Rate Limits & Paging for how the limits count, how to retry, and how to page through results. Contact us if you need higher limits.

Errors

Get Summary

Counts for one run, computed for you — use this for totals and charts instead of paging through every result.

Required query parameter run_id (from Campaigns & Runs). Without it the request is refused with 400; a run that is not part of the campaign returns 404. Optional from / to (ISO 8601, from inclusive, to exclusive) count only calls placed in that period, exactly as in Get Results; the response repeats it as period.

Response — 200 OK

{
  "campaign_id": "0b7c9a52-6f0e-4c3d-9a7e-2f6d1c8e4b10",
  "run_id": "9f1d2e3c-4b5a-4c6d-8e7f-0a1b2c3d4e5f",
  "attempt_no": 2,
  "previous_run_id": "3c7e1b90-5d2a-4f18-a6b4-91e0d8c2f4a7",
  "period": { "from": null, "to": null },
  "as_of": "2026-09-30T10:00:00.000Z",
  "planned": 9800,
  "contacts": 9210,
  "connected": 4900,
  "by_outcome": { "connected": 4900, "no_answer": 3100, "busy": 800, "in_progress": 410 },
  "by_disposition": { "PROMISE_TO_PAY": 1500, "CALLBACK_REQUESTED": 320, "none": 4310 },
  "promise_to_pay": 1500
}

Manage Webhooks

Subscribe an endpoint to call events. This is the recommended way to receive results: deliveries are signed, retried, and cover every call your organisation places through this API. Requires an admin (or owner) key.

List — response 200

{
  "webhooks": [
    {
      "id": "5b0c2f5e-3c1d-4e0a-9d64-0b9d7a1f2c88",
      "url": "https://your-server.com/hooks/audatec",
      "events": ["call.completed", "call.failed", "call.rejected"],
      "is_active": true
    }
  ]
}

The signing secret is never returned by the list or update calls — only once, when the subscription is created.

Create — request

{
  "url": "https://your-server.com/hooks/audatec",
  "events": ["call.completed", "call.failed", "call.rejected"]
}

Create — response 201

{
  "id": "5b0c2f5e-3c1d-4e0a-9d64-0b9d7a1f2c88",
  "url": "https://your-server.com/hooks/audatec",
  "events": ["call.completed", "call.failed", "call.rejected"],
  "is_active": true,
  "secret": "whsec_kT3...",
  "warning": "Store this secret now — it is needed to verify delivery signatures and is not retrievable later."
}

Update — request

PATCH /integration/v1/webhooks/{id} with any of the fields below; the ones you leave out stay as they are. Send at least one.

{
  "events": ["call.completed", "call.failed"],
  "is_active": false
}

Returns 200 with the updated subscription (id, url, events, is_active; no secret).

Errors

Call Notifications

Receive call results without polling. There are two ways: a webhook subscription (recommended — durable, retried) or a per-call callback_url (one best-effort attempt).

Notification payload

{
  "event": "call.completed",
  "call_id": "31106b7c-9d02-4723-8b07-5bb8d90240cb",
  "status": "ended",
  "outcome": "connected",
  "duration_secs": 97,
  "disposition": "PROMISE_TO_PAY",
  "transcript_url": null,
  "recording_url": null,
  "occurred_at": "2026-06-14T10:33:42.000Z"
}

{
  "event": "call.failed",
  "call_id": "91a2b3c4-d5e6-7f8a-9b0c-1d2e3f4a5b6c",
  "status": "ended",
  "outcome": "no_answer",
  "duration_secs": null,
  "disposition": null,
  "transcript_url": null,
  "recording_url": null,
  "occurred_at": "2026-06-14T11:05:10.000Z"
}

The payload carries the call's status and outcome (see Call Status Values). disposition, duration_secs and the URLs are only filled in when the agent recorded a result (normally on call.completed); on the other events they are null. Your own metadata is not included — match on call_id.

Event types

Delivery headers

Signature verification

Verify the signature on the raw body before processing:

const crypto = require('crypto');

// rawBody: the exact request body bytes (do not re-serialise the parsed JSON)
function verifySignature(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  const a = Buffer.from(signatureHeader || '');
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Endpoint requirements & retries

• Return HTTP 2xx within 10 seconds. If processing takes longer, respond 200 immediately and handle the payload asynchronously.
• Webhook subscriptions are retried on a non-2xx response or timeout: after 10 s, 1 min, 5 min, 30 min and 2 h — six attempts in total, after which the delivery is dropped.

callback_url (per call)

• Same payload and headers as above.
• Signed with the secret of your organisation's first active webhook subscription. If you have none, it is signed with a shared default secret, so you cannot verify it — create a subscription to get a secret you own.

Webhooks vs callback_url vs Polling

Three ways to receive call results. Use a webhook subscription for any production system.

Webhook subscription Recommended

Create a subscription once with POST /webhooks. Audatec then POSTs every selected event for every call you place through the API — no repeated requests and no per-call setup.

• Reliable — failed deliveries are retried for hours, and each delivery has a unique id so you can deduplicate
• Complete — answered, completed, failed and rejected calls are all covered
• Scales linearly — 1000 concurrent calls still means about 1000 deliveries, not 1000 × N polls
• Verified with X-Audatec-Signature (HMAC-SHA256) so you can reject spoofed requests

callback_url

A URL passed on a single trigger request. Convenient for quick tests, but one best-effort attempt only: no retries, and not sent for carrier-level failures. Do not rely on it for production results.

Polling

If you can't expose a public endpoint (local development, scripts, one-off jobs), poll GET /calls/{call_id}/status until is_terminal is true.

• No inbound server required
• Keep the interval at 4–5 seconds minimum — tighter loops waste quota without benefit
• Stop immediately once is_terminal: true
• Not recommended at scale: 100 concurrent calls at 4 s intervals = 25 req/s of pure overhead

async function waitForCall(callId, apiKey) {
  const url = `https://api.audatec.in/integration/v1/calls/${callId}/status`;
  while (true) {
    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` }
    });
    const data = await res.json();
    if (data.is_terminal) return data;
    await new Promise(r => setTimeout(r, 4000)); // poll every 4s
  }
}

Error Handling

All errors return JSON with an error field describing what went wrong.

{ "error": "metadata missing required keys: amount_due, due_date" }

Common errors

Retry strategy

Different status codes call for different retry behaviour:

• 400 / 403 / 404 — Do not retry. Fix the request or the key.
• 401 — Do not retry. Check your API key.
• 429 — The call was not queued. Retry after the Retry-After header value (seconds).
• 502 / 503 — Retry with exponential backoff (1s, 2s, 4s…), and send an Idempotency-Key so a retry can never place a second call.

Rate Limits & Paging

How much you can read, how to read it in pages, and what to do when you hit a limit. Applies to the results endpoints: Campaigns & Runs, Get Results and Get Summary.

The limits

These limits apply to each API key separately. Contact us if you need more. Calling a different endpoint, such as POST /calls, is limited separately by your trunk allocation (see Trigger a Call).

How the limits count

• The request limit is a fixed one-minute window that starts on the clock minute. Every request counts, including ones that were refused with 429, so do not hammer the endpoint while waiting.
• The row allowance is checked before a page is read and charged after it is sent, so the last page of the day can take you slightly over the 500,000.
• Only /results rows count towards the daily allowance. /summary, /runs and /campaigns cost a request but no rows.

Response headers

When you hit a limit

Always honour Retry-After. For anything else that is temporary (502, 503 without a code, a network error), retry with exponential backoff and a little random jitter, and give up after a few attempts. Do not retry 400, 401, 403 or 404: fix the request or the key.

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function getJson(url, apiKey, maxAttempts = 5) {
  for (let attempt = 1; ; attempt++) {
    let res;
    try {
      res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
    } catch (err) {                                   // network error: retry
      if (attempt >= maxAttempts) throw err;
      await sleep(2 ** attempt * 500 + Math.random() * 250);
      continue;
    }
    if (res.ok) return res.json();

    const body = await res.json().catch(() => ({}));
    if (res.status === 429 || res.status === 503) {
      if (body.code === 'daily_quota_exceeded') throw new Error('Daily row allowance used up');
      if (attempt >= maxAttempts) throw new Error(`Gave up: ${res.status} ${body.code || ''}`);
      const wait = Number(res.headers.get('retry-after')) || 2 ** attempt;
      await sleep(wait * 1000 + Math.random() * 500);    // honour Retry-After
      continue;
    }
    if (res.status >= 500 && attempt < maxAttempts) {   // other temporary failure
      await sleep(2 ** attempt * 500 + Math.random() * 250);
      continue;
    }
    throw new Error(`${res.status}: ${body.error || 'request failed'}`);
  }
}

Paging

Lists are returned in pages. Every paged response has a pagination object:

"pagination": { "limit": 250, "has_more": true, "next_cursor": "eyJwIjoiKzkxOTg3NjU0MzIxMCJ9" }

• Request the next page by sending next_cursor back as the cursor parameter, with the same run_id and filters. Keep going while has_more is true; on the last page next_cursor is null.
• A cursor is an opaque token. Do not build, edit or store it long term. A malformed cursor returns 400.
• /results is ordered by phone_number (up to 250 rows a page). /runs and /campaigns are ordered newest first (up to 200 a page).
• Use limit to change the page size within the maximums above. A smaller page is a smaller, faster response.

async function readRun(campaignId, runId, apiKey, onRows) {
  const base = `https://api.audatec.in/integration/v1/campaigns/${campaignId}/results`;
  let cursor = null;
  do {
    const url = new URL(base);
    url.searchParams.set('run_id', runId);
    url.searchParams.set('limit', '250');
    if (cursor) url.searchParams.set('cursor', cursor);

    const page = await getJson(url.toString(), apiKey);   // retries and Retry-After handled above
    await onRows(page.results);

    cursor = page.pagination.has_more ? page.pagination.next_cursor : null;
    await sleep(1100);          // stay under 60 requests a minute
  } while (cursor);
}

Reading efficiently

• Read a finished run once. A run whose status is completed rarely changes. Keep refreshing only the runs that are still in progress.
• Fetch only what changed. Store the largest updated_at you have seen for each run and pass it as updated_since next time.
• Use the summary for totals. Get Summary returns counts for a whole run in one request and uses no rows from your allowance.
• Narrow by time. Add from and to to read only the calls placed in a period.
• Plan your budget. The daily allowance is about 2,000 full pages of 250 rows. A run of 100,000 contacts is 400 pages and uses 100,000 of the 500,000 rows.
• Do not poll tightly. Refreshing about once a minute is plenty; the data is calculated when you ask for it.

Call Status Values

A call has a status (where it is) and, once it has ended, an outcome (how it ended).

status

Status only moves forward: queued → ringing → in_progress → ended.

outcome

null until status is ended.

Error Codes

HTTP status codes returned by the API.