Reading calls

Two endpoints, both server-to-server with your API key: a slim list that answers "all calls for this agency" and "all calls for this rep", and a full detail for one call's transcript, score and recording. Practice calls (roleplay) and real calls (real_call) have the same shape, and you read them one source at a time: source is required on the list.

List — GET /v1/calls

Returns scored calls of one source for your tenant, newest first (roleplay by endedAt, real_call by startedAt), cursor-paginated.

Query parameters

Response — a slim row per call (no score, no transcript):

{
  "data": [
    {
      "id": "athos_call_GZ1DjOkZv_VEPoE-CJ8mp",
      "source": "roleplay",
      "agencyId": "athos_agency_V1StGXR8Z5jdHi6B-myT",
      "agentId": "athos_agent_bR4kQ2wZ9Lp0nH3xVq1Yt",
      "platformAgentId": "rep_8842",
      "platformAgencyId": "acme-7731",
      "drillKey": "ma-full-sale",
      "startedAt": "2026-06-05T14:39:40.295Z",
      "endedAt": "2026-06-05T14:49:52.295Z",
      "durationSec": 612,
      "scoredAt": "2026-06-05T14:50:29.005Z"
    }
  ],
  "nextCursor": "eyJ0IjoxNzQ5…"
}

Every key is always present. platformAgentId / platformAgencyId are null when you never registered one — join on agentId / agencyId then (see Core concepts). drillKey is null on a real_call. Page with cursor and the same source, as described in Paging.

Reconciling by polling

from and to filter on the call's own time, not on when it was scored — when it ended for a roleplay call, when it started for a real_call — and results are ordered on that same axis. Scoring finishes minutes after a call ends, so a call can become readable inside a window you have already read past. When you reconcile (the backstop for a missed webhook delivery), re-scan a window that overlaps the last one by an hour plus the longest real call you expect, and deduplicate on id. A forward-only watermark misses calls that were scored after you read past them.

# every practice call for one agency (source=real_call for its real calls)
curl -G https://app.useathos.ai/api/external/v1/calls \
  -H "Authorization: Bearer $ATHOS_API_KEY" \
  --data-urlencode "from=2026-06-01T00:00:00Z" \
  --data-urlencode "source=roleplay" \
  --data-urlencode "agencyId=athos_agency_V1StGXR8Z5jdHi6B-myT" \
  --data-urlencode "limit=50"

async function* callsFor(
  from: string,
  source: 'roleplay' | 'real_call',
  scope: { agencyId?: string; agentId?: string },
) {
  let cursor: string | null = null;
  do {
    const url = new URL('https://app.useathos.ai/api/external/v1/calls');
    url.searchParams.set('from', from);
    url.searchParams.set('source', source);
    if (scope.agencyId) url.searchParams.set('agencyId', scope.agencyId);
    if (scope.agentId) url.searchParams.set('agentId', scope.agentId);
    if (cursor) url.searchParams.set('cursor', cursor);
    const r = await fetch(url, { headers: { Authorization: `Bearer ${process.env.ATHOS_API_KEY}` } });
    if (r.status === 404) throw new Error((await r.json()).error.code); // AGENCY_NOT_FOUND / AGENT_NOT_FOUND
    const page = await r.json();
    yield* page.data;
    cursor = page.nextCursor;
  } while (cursor);
}

// one rep's practice calls, newest first — a second loop with 'real_call' reads their real calls
for await (const call of callsFor('2026-06-01T00:00:00Z', 'roleplay', { agentId: rep.agentId })) {
  console.log(call.id, call.drillKey, call.scoredAt);
}

GET /v1/calls is a history read — scored calls only, never in-progress ones. The call.scored webhook is your notification; use this endpoint to render history and to reconcile.

Detail — GET /v1/calls/:callId

Look up one call of either source by its public id (from a list row, a webhook callId, or the SDK ended event). An unknown id and another tenant's id both answer 404 CALL_NOT_FOUND.

curl https://app.useathos.ai/api/external/v1/calls/athos_call_GZ1DjOkZv_VEPoE-CJ8mp \
  -H "Authorization: Bearer $ATHOS_API_KEY"

Response (roleplay; complianceScorecard abridged):

{
  "id": "athos_call_GZ1DjOkZv_VEPoE-CJ8mp",
  "source": "roleplay",
  "status": "scored",
  "agencyId": "athos_agency_V1StGXR8Z5jdHi6B-myT",
  "agentId": "athos_agent_bR4kQ2wZ9Lp0nH3xVq1Yt",
  "platformAgentId": "rep_8842",
  "platformAgencyId": "acme-7731",
  "drillKey": "ma-full-sale",
  "startedAt": "2026-06-05T14:39:40.295Z",
  "endedAt": "2026-06-05T14:49:52.295Z",
  "durationSec": 612,
  "scoredAt": "2026-06-05T14:50:29.005Z",
  "transcript": [
    { "role": "agent", "content": "Hi, this is Sam from the benefits line." },
    { "role": "beneficiary", "content": "Yeah, I saw something about the grocery card." }
  ],
  "score": {
    "overallScore": 82,
    "summary": "Prospect asked about Medicare options; the agent built rapport but rushed the close.",
    "feedback": "Lead with a clear greeting and one discovery question; slow down before presenting the plan.",
    "compliancePercent": 85,
    "complianceScorecard": {
      "requiredCallOpening": {
        "statedNameAndAgency": {
          "yesNo": "yes",
          "score": 5,
          "explanation": "The agent gave their name and the agency in the first ten seconds."
        },
        "statedCallIsRecorded": {
          "yesNo": "yes",
          "score": 3,
          "explanation": "The agent said the call was recorded before asking any questions."
        }
      },
      "scopeOfAppointment": {
        "confirmedProductsToDiscuss": {
          "yesNo": "no",
          "explanation": "The agent moved into the plan comparison without confirming the scope on file."
        }
      }
    }
  },
  "audioUrl": "https://…/athos_call_GZ1DjOkZv_VEPoE-CJ8mp.ogg?X-Amz-Expires=3600&X-Amz-Signature=…",
  "audioUrlExpiresAt": "2026-06-05T15:50:29.005Z",
  "waveform": null,
  "createdAt": "2026-06-05T14:39:45.000Z",
  "updatedAt": "2026-06-05T14:50:29.100Z"
}

The detail is a list row plus status (always "scored"), transcript, score, audioUrl, audioUrlExpiresAt, waveform (reserved, always null), createdAt and updatedAt.

The transcript

A flat list of turns, in the order they were spoken. The same shape for both sources.

The score object

summary and feedback are always present but either can be an empty string — on a very short call, or when the analysis step did not complete, the call still scores but has no prose.

Recording playback

audioUrl is either a short-lived signed link to Athos's own archived recording — with audioUrlExpiresAt set to the moment it stops working, about an hour after the request — or null, in which case audioUrlExpiresAt is null too and there is nothing to play (a real call whose recording was not archived, a real call older than 30 days — its archived recording has been deleted — or the rare case where a recording exists but could not be prepared, which a later request usually resolves).

Use the link directly in an <audio> element or a download link. Do not store it, email it or embed it anywhere long-lived: when you need it again, fetch the call again and you get a fresh one. The link is signed for GET only — a HEAD request answers 403; to inspect the file without downloading it, send a ranged GET (Range: bytes=0-0). On a real_call it is never the dialer's own recording URL.