Calls

List and inspect every call your agents handle: read transcripts and grades, export recordings and structured data, and report issues on calls that need review.

Every inbound call to your phone numbers, every call triggered from POST /v1/call, every browser mic session, and every widget call produces a call log record. These endpoints let you enumerate and inspect them, fetch recordings and transcripts, record AI quality grades, file issue reports, and export history.

Endpoints#

Call object#

{
  "call_id": 987654321,
  "agent_id": 12,
  "agent_variant_id": null,
  "agent_variant_label": null,
  "direction": "inbound",
  "from_number": "+14155550199",
  "to_number": "+15551234567",
  "start_time": "2026-04-20T18:24:10.113Z",
  "end_time": "2026-04-20T18:25:04.822Z",
  "duration_seconds": 54,
  "status": "completed",
  "end_reason": "user_hangup",
  "outbound_dial_sip_status": null,
  "outbound_dial_sip_reason": "",
  "outbound_dial_sip_kind": null,
  "recording_url": null,
  "recording_started_at": "2026-04-20T18:24:12.501Z",
  "recording_stopped_at": null,
  "recording_stopped_reason": null,
  "consent_evidence": {},
  "is_simulation": false,
  "is_test_call": false,
  "is_scenario_call": false,
  "prompt_snapshot": "You are a helpful support agent for Acme Ops…",
  "tool_snapshot": [],
  "cloud_run_execution_name": null,
  "livekit_room_name": "call-987654321",
  "livekit_room_sid": "RM_xxxxxxxxxxxx",
  "product": "spark",
  "voice": "john",
  "billable_minutes": 1.25,
  "billing_total_cents": 3,
  "billed_at": "2026-04-20T18:25:05.101Z",
  "transfer_outcome": null,
  "transfer_bridge_kind": null,
  "transfer_destination": "",
  "transfer_sip_status": null,
  "transfer_bridge_seconds": null,
  "transfer_bridge_total_cents": null,
  "voip_connection_id": null,
  "grade_score": 92,
  "grade_status": "completed",
  "grade_updated_at": "2026-04-20T18:25:11.002Z",
  "call_outcome": "success",
  "extracted_data": {
    "status": "completed",
    "fields": {
      "customer_name": "Alex Morgan",
      "appointment_date": "2026-04-23"
    },
    "evidence": {
      "customer_name": {
        "quote": "My name is Alex Morgan",
        "speaker_role": "caller",
        "turn_index": 4
      },
      "appointment_date": {
        "quote": "April 23 works for me",
        "speaker_role": "caller",
        "turn_index": 7
      }
    },
    "verification": "verified",
    "field_reasons": {},
    "schema_version": "92850758e231a3c95a...",
    "schema_snapshot": [
      { "key": "customer_name", "type": "string", "description": "Caller's full name" },
      { "key": "appointment_date", "type": "date", "description": "Requested appointment date" }
    ],
    "extracted_at": "2026-04-20T18:25:09.120Z"
  },
  "issue_count": 0,
  "critical_issue_count": 0,
  "summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23.",
  "summary_status": "completed",
  "report": {
    "status": "completed",
    "outcome_key": "appointment_set",
    "outcome_label": "Appointment set",
    "outcome_color": "green",
    "outcome_reasoning": "A follow-up visit was booked on the call.",
    "needs_attention": false,
    "attention_reason": "",
    "attention_note": "",
    "attention_turn_index": null,
    "attention_time_seconds": null,
    "caller_name": "Alex",
    "caller_is_new": false,
    "call_reason": "Book a follow-up visit",
    "one_line_summary": "Alex, follow-up visit, booked Thu Apr 23",
    "caller_frustrated": false,
    "frustration_cause": "",
    "caller_experience_note": "Alex was comfortable talking to the assistant.",
    "hangup_stage": "",
    "handled_start_to_finish": true,
    "appointment_set": true,
    "appointment_new_client": false,
    "transfer_result": "not_attempted",
    "booking_result": "succeeded",
    "detail_capture_trouble": false,
    "generated_at": "2026-04-20T18:25:11.002Z"
  }
}

Consent evidence#

Calls on agents with the consent announcement enabled carry a read-only consent_evidence object recording exactly what played and what the caller did afterwards:

continuation_event and objection_events document caller behavior around the notice; they are not proof the caller heard the announcement and are not a substitute for affirmative (press-1) consent where a jurisdiction requires it.

List calls#

curl 'https://api.thunderphone.com/v1/calls?limit=50' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

page = requests.get(
    "https://api.thunderphone.com/v1/calls",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    params={"limit": 50, "direction": "inbound"},
).json()
for call in page["results"]:
    ...

const url = new URL("https://api.thunderphone.com/v1/calls");
url.searchParams.set("limit", "50");
const page = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}` },
}).then((r) => r.json());

Query parameters#

Paginated response#

{
  "results": [ /* Call objects */ ],
  "total": 1234,
  "limit": 50,
  "offset": 0
}

Use offset + limit to page forward; check total to know when you've reached the end.

Call report#

A call's report is the customer-facing read of what happened. It is null until grading writes one. For a conversation, the full grade writes the report in the same model pass. When recording is enabled, calls that end before a conversation and calls with no transcript get a basic report without a model pass. An early heuristic grade can leave report as null. While batch grading is queued, report.status may be pending; its fields are placeholder defaults, not findings, so read them only when status is completed. Calls made with recording disabled get a report with status skipped and no findings. If full grading fails, a report may stay null or pending; that does not mean the call needs no follow-up.

The outcome comes from the agent's outcome_labels (Success / Failure unless the agent defines its own list). The agent's report_instructions ask the grader how to write one_line_summary, call_reason, caller_experience_note and attention_note. For example, you can ask it to omit health details. These are AI writing instructions, not guaranteed redaction. They do not change the transcript, recording or the separate Call object's summary.

The same object rides on the call.graded event.

Report summary#

GET /v1/calls/report-summary

Returns the five call-report numbers shown on dashboard Home and in each agent's Calls tab. It compares the selected date range with the previous period of the same length. Counts always leave out the organization's excluded test numbers.

{
  "period": { "start": "2026-08-25T07:00:00Z", "end": "2026-09-24T07:00:00Z" },
  "previous_period": { "start": "2026-07-26T07:00:00Z", "end": "2026-08-25T07:00:00Z" },
  "timezone": "America/Los_Angeles",
  "has_business_hours": true,
  "excluded_numbers": 2,
  "metrics": {
    "calls_handled": { "value": 212, "previous": 187, "after_hours": 61, "after_hours_previous": 48, "good_direction": "up" },
    "handled_start_to_finish": { "value": 150, "previous": 121, "good_direction": "up" },
    "went_badly": { "value": 19, "previous": 26, "breakdown": { "hung_up": 9, "detail_capture_trouble": 5, "booking_failed": 3, "transfer_failed": 2 }, "good_direction": "down" },
    "caller_experience": { "value": 171, "previous": 140, "conversations": 180, "frustrated": 9, "frustrated_previous": 14, "top_cause": "wanted_a_person", "top_cause_count": 4, "causes": [ { "cause": "wanted_a_person", "count": 4 } ], "good_direction": "up" },
    "appointments_set": { "value": 64, "previous": 51, "new_clients": 22, "new_clients_previous": 15, "good_direction": "up" }
  },
  "needs_attention": { "value": 14, "previous": 20, "reasons": [ { "reason": "caller_frustrated", "count": 6 } ] },
  "success_rate": { "graded": 198, "succeeded": 171, "graded_previous": 170, "succeeded_previous": 139 },
  "outcomes": [ { "key": "appointment_set", "label": "Appointment set", "count": 64 } ],
  "agents": [
    { "agent_id": 12, "agent_name": "Front desk", "calls": 140, "after_hours": 40, "handled": 101, "went_badly": 11, "frustrated": 5, "no_frustration": 118, "conversations": 123, "appointments": 48, "appointments_new": 17, "needs_attention": 9, "graded": 132, "succeeded": 116, "reported": 136 }
  ],
  "reported": 205,
  "pending_reports": 7
}

good_direction says which way is good for each metric; colour arrows by it, not by their sign (fewer calls that went badly is green).

Every report metric counts answered calls only: non-rejected inbound and web calls, plus outbound calls once the other side answered. Browser tests and simulations are left out, matching the Home call-volume chart. calls_handled is that count. caller_experience.value counts judged conversations with no frustration; frustrated and frustrated_previous count frustrated callers (the dashboard shows those). went_badly.value counts calls with a hang-up mid-conversation or after the ask, trouble getting a detail right, a failed booking or a failed transfer; one call can fall in several breakdown buckets. reported counts calls with a completed report and pending_reports the answered calls still waiting for one (a skipped report is not pending). excluded_numbers is the number of configured test numbers. It is not a count of excluded calls, and it includes configured numbers with no calls in this date range. agents is the same breakdown per agent for the current period, busiest first; an agent with its own business_hours is judged by them for after-hours.

Export calls#

Bulk-download up to 1,000 of the most recent calls as either CSV (metadata only) or JSON (includes transcripts). The export honors the same filter parameters as List calls, so what you export matches what you filtered. Both formats carry the report columns (outcome, needs_attention, attention_reason, caller_name, caller_is_new, call_reason, summary, caller_frustrated, hangup_stage, appointment_set, ...), blank until the call has a completed report.

curl 'https://api.thunderphone.com/v1/calls/export?export_format=csv' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -o calls.csv

curl 'https://api.thunderphone.com/v1/calls/export?export_format=json&status=completed&start_date=2026-07-01T00:00:00Z' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -o calls.json

Query parameters#

limit/offset are not accepted — the export always returns the most recent matches up to its fixed cap.

Response#

The response includes a Content-Disposition: attachment header with a dated filename (calls-export-YYYY-MM-DD.csv).

Exports cap at the 1,000 most recent calls matching the filters. When more calls match than the cap allows, the response carries truncation signals so you can detect an incomplete export:

For a truncated window, narrow the date range (start_date/end_date) and export in slices, or use the list endpoint with offset pagination.

List party numbers#

Distinct phone numbers that have appeared on either side of your organization's calls, most recently seen first. Use it to autocomplete the from_number / to_number filters of List calls — it includes external callers, not only numbers you own. Placeholder parties for browser, widget and test sessions are omitted.

curl 'https://api.thunderphone.com/v1/calls/party-numbers?q=631456' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Query parameters#

Response#

{
  "numbers": ["+16314566068", "+15137061124"]
}

Retrieve a call#

curl https://api.thunderphone.com/v1/calls/987654321 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Returns 200 OK with a Call object, or 404 if the call does not belong to your organization.

Delete a call#

Permanently deletes one call and its content. Only owners and admins can delete calls. An API key acts with the role of the user who created it, so a key created by a member gets 403.

curl -X DELETE https://api.thunderphone.com/v1/calls/987654321 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Deleting a call removes:

• the recording and every other stored audio file for the call
• the transcript and the full turn history
• the summary, call report, extracted data and AI grades
• issue reports filed on the call
• stored copies of webhook events about the call
• validation examples made from the call, with their copied turns and caller audio

Your billing history keeps the charge for the call (amount, billed minutes and call ID) without any call content, so balances and invoices do not change. Test scenarios created from the call and text messages sent during it are separate records and are not deleted. To see how many validation examples a deletion would remove before you delete, use Preview a deletion.

The call disappears from the API and the dashboard as soon as the request returns. Stored files are deleted in the background, normally within a minute, and a recently ended call's storage is checked again an hour later for a recording that finished uploading after the delete. Backups age out on a roughly 35-day cycle, and a deleted call is deleted again if a backup is ever restored. Deletion cannot be undone and sends no webhook event.

Delete calls in bulk#

POST /v1/calls/bulk-delete deletes up to 100 calls in one request, with the same rules and effects as deleting one call. The response has one result per distinct call ID.

curl -X POST https://api.thunderphone.com/v1/calls/bulk-delete \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"call_ids": [987654321, 987654322, 987654323]}'

{
  "results": [
    {"call_id": 987654321, "status": "deleted", "detail": ""},
    {"call_id": 987654322, "status": "not_found", "detail": ""},
    {"call_id": 987654323, "status": "in_progress", "detail": "This call is still in progress. Wait for it to end, then delete it."}
  ],
  "deleted": 1
}

The request returns 400 for an empty list, more than 100 IDs, or IDs that are not positive integers, and 403 when the authenticated user is not an owner or admin.

Preview a deletion#

POST /v1/calls/bulk-delete/preview takes the same body as bulk delete and deletes nothing. It returns how many validation examples were made from those calls, which deleting them would also remove. IDs that are not calls in your organization count nothing. Owners and admins only, like deletion.

curl -X POST https://api.thunderphone.com/v1/calls/bulk-delete/preview \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"call_ids": [987654321, 987654322]}'

{
  "validation_examples": 2
}

The request returns 400 and 403 in the same cases as bulk delete.

Get recording audio#

Returns a short-lived signed URL to the MP3 recording on Google Cloud Storage. Stream the URL directly to your audio player — do not store it (it expires).

curl https://api.thunderphone.com/v1/calls/987654321/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{ "url": "https://storage.googleapis.com/thunderphone-recordings/..." }

Get caller audio#

GET /v1/calls/{call_id}/caller-audio?ref={ref}

Streams what the caller actually said for one turn of the conversation. ref comes from a transcript entry's caller_audio_refs, present on caller turns whose audio was captured.

Get consent announcement audio#

GET /v1/consent-announcements/{asset_hash}

Streams the exact consent-announcement asset that played at the start of a call, as a 48 kHz mono WAV. Calls that played an announcement carry a consent_evidence object (asset hash, announcement text, playback and capture timestamps); pass its asset_hash here to retrieve the audio whose content hash matches it byte-for-byte. This endpoint is the programmatic evidence-access path; the stored call recording itself also begins with this announcement — it is muxed in at recording finalization, and consent_evidence then carries recording_announcement_offset_seconds / recording_announcement_duration_seconds marking where the prepended segment sits inside the recording. When additional participants joined mid-call (for example a warm-transfer target), the same object also carries a legs array — one entry per joining leg with the leg's identity, join time, its own playback/capture timestamps for the same content-addressed asset, and post-notice continuation details.

Authorization is by evidence linkage: the hash must appear in the consent_evidence of a call your organization can access. Responses are never cacheable (Cache-Control: no-store), and the endpoint is rate-limited per user.

curl https://api.thunderphone.com/v1/consent-announcements/f1d6b49f4ac8f391cfc933591f53415bc71083a62d723acb4de5606cea3d4d73 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  --output consent-announcement.wav

Get transcript#

Simplified, user-facing transcript (role-tagged speech only; no system events). For the full structured history including function calls, interruptions, and latency metrics use /history.

curl https://api.thunderphone.com/v1/calls/987654321/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "call_id": 987654321,
  "transcripts": [
    {
      "role": "user",
      "content": "Hi, I have a question about my policy.",
      "start_ms": 1200,
      "end_ms": 3400,
      "caller_audio_refs": ["…", "…"]
    },
    {
      "role": "agent",
      "content": "Of course — could I have your member id?",
      "start_ms": 3800,
      "end_ms": 6100,
      "ttfa_ms": 412
    }
  ]
}

Caller audio is always the call audio as received, never a noise-suppressed version, so re-listening to two different turns is always comparing like with like. A long caller turn can span several recordings; fetch them in the order given and concatenate.

Get history#

Full structured turn history. Use this when you need raw function-call arguments, interruption markers, ack-prompt annotations, or first-byte latencies.

curl https://api.thunderphone.com/v1/calls/987654321/history \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Returns an array of typed entries. See the ThunderPhone call-history schema reference for the full shape — the top-level entries include span, completion, patch, function_call, function_response, interrupt, and acknowledgement.

AI call grading#

Get latest grade#

curl https://api.thunderphone.com/v1/calls/987654321/grade \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "id": 88,
  "call_id": 987654321,
  "status": "completed",
  "score": 92,
  "call_outcome": "success",
  "outcome_reasoning": "The caller's policy question was answered fully and confirmed.",
  "summary": "Caller asked about their policy and got a full answer…",
  "rubric_breakdown": { "accuracy": 95, "tone": 90 },
  "detected_issues": [],
  "grader_model": "heuristic-v1",
  "grader_version": "v1",
  "error_message": null,
  "graded_at": "2026-04-20T18:25:11.002Z",
  "created_at": "2026-04-20T18:25:11.002Z",
  "updated_at": "2026-04-20T18:25:11.002Z"
}

Returns 200 OK with the latest grade row, or 404 if the call has not been graded.

Run grading#

Grade the call. Grading runs synchronously within the request. If a completed grade already exists it is returned as-is unless you pass force=true.

Any request that would invoke the grader — a forced regrade, or a request whose latest grade is missing, pending, or failed — must first claim a per-call cooldown. The standard cooldown is 15 minutes. If the latest grade is a retryable failure, the cooldown is 90 seconds so a retry can recover sooner. At most one new grading run can be claimed per window.

curl -X POST 'https://api.thunderphone.com/v1/calls/987654321/grade?force=true' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

A request inside the active cooldown returns 429 Too Many Requests. The Retry-After response header and retryAfterSeconds body field contain the same number of seconds to wait:

{
  "detail": "This call was recently submitted for grading. Please retry later.",
  "retryAfterSeconds": 90
}

Run data extraction#

Re-run structured data extraction for a completed call using the agent's current deployed extraction schema. This admin-only endpoint overwrites the call's prior extraction row and emits call.data_extracted when extraction completes.

curl -X POST https://api.thunderphone.com/v1/calls/987654321/extract \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "id": 412,
  "call_id": 987654321,
  "agent_id": 12,
  "schema_snapshot": [
    {
      "key": "customer_name",
      "type": "string",
      "description": "The caller's full name",
      "required": true,
      "ask": true
    }
  ],
  "schema_version": "92850758e231a3c95a...",
  "data": {"customer_name": "Alex Morgan"},
  "evidence": {
    "customer_name": {
      "quote": "My name is Alex Morgan",
      "speaker_role": "caller",
      "turn_index": 4
    }
  },
  "verification": "verified",
  "field_reasons": {},
  "status": "completed",
  "error_message": "",
  "model": "<model id>",
  "extracted_at": "2026-04-20T18:25:11.002Z",
  "created_at": "2026-04-20T18:25:11.002Z",
  "updated_at": "2026-04-20T18:25:11.002Z"
}

The response is still 200 OK when the extraction row has status="failed" or status="skipped"; inspect error_message for the reason. Calls whose immutable recording policy disabled retained content return 409 Conflict with status="skipped_recording_disabled" and are never sent to the model. A call outside the authenticated organization returns 404.

Issue reports#

Issue reports let your team (or automated grading) flag specific calls for review. Reports have a severity and optional title/description and appear in the org-wide Issue Reports feed.

List reports for a call#

curl https://api.thunderphone.com/v1/calls/987654321/issue-reports \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Returns an array of Issue Report objects — see Issue Reports.

File a report#

curl -X POST https://api.thunderphone.com/v1/calls/987654321/issue-reports \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Agent paused too long",
    "description": "Five second silence before responding to the main question.",
    "severity": "warning"
  }'

Returns 201 Created with the Issue Report object. To update a report's status later, use the issue-reports endpoints (reports are addressed by trace_id).

Live call supervision#

Both endpoints work only while status="in_progress"; once the call ends they return 409 Conflict with {"detail": "Call is not live."}. The dashboard's Live page is built on the same primitives.

Listen in#

Mints a hidden, subscribe-only token for the call's media room. The listener is invisible: the agent, the caller, and the recording are unaffected.

curl -X POST https://api.thunderphone.com/v1/calls/987654321/listen \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "token": "eyJhbGciOi...",
  "room_name": "call-987654321",
  "server_url": "wss://livekit.thunderphone.com"
}

Connect to server_url with a LiveKit client SDK using token and subscribe to the room's audio. The token is valid for up to 2 hours; the session ends when the call's room closes.

Whisper to the agent#

Sends private text guidance that only the agent hears — the caller is never aware of it. The agent weaves the guidance into its next turns. Use it to coach an agent through an unusual situation mid-call.

curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Offer the caller a 10% discount if they mention cancelling."}'

{ "status": "sent" }

Related#