Calls

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

Method	Path	Description
`GET`	`/v1/calls`	List calls (paginated, filterable)
`GET`	`/v1/calls/export`	Bulk export up to 1,000 calls as CSV or JSON
`GET`	`/v1/calls/{call_id}`	Retrieve a single call
`GET`	`/v1/calls/{call_id}/audio`	Get a time-limited recording URL
`GET`	`/v1/calls/{call_id}/transcript`	Fetch the transcript
`GET`	`/v1/calls/{call_id}/history`	Fetch the full structured turn history
`GET`	`/v1/calls/{call_id}/grade`	Fetch the latest AI quality grade
`POST`	`/v1/calls/{call_id}/grade`	Run (or re-run) AI grading
`GET`	`/v1/calls/{call_id}/issue-reports`	List issue reports for a call
`POST`	`/v1/calls/{call_id}/issue-reports`	File an issue report

Call object

{
  "call_id": 987654321,
  "agent_id": 12,
  "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": "caller_hangup",
  "recording_url": null,
  "is_test_call": false,
  "product": "spark",
  "voice": "en-US-James1",
  "billable_minutes": 1,
  "billing_total_cents": 8,
  "billed_at": "2026-04-20T18:25:05.101Z",
  "grade_score": 0.92,
  "grade_status": "completed",
  "grade_updated_at": "2026-04-20T18:25:11.002Z",
  "issue_count": 0,
  "critical_issue_count": 0
}

Field	Type	Description
`call_id`	integer	Server-assigned call id (also the key in every other endpoint on this page)
`agent_id`	integer \| null	Agent that handled the call
`direction`	string	`inbound`, `outbound`, `mic`, or `widget`
`from_number`	string	E.164 caller number. `mic` sessions use an internal identifier
`to_number`	string	E.164 destination number
`start_time`, `end_time`	timestamp \| null	ISO 8601 UTC. `end_time` is null while `status="in_progress"`
`duration_seconds`	integer \| null	Derived
`status`	string	`in_progress`, `completed`, or `failed`
`end_reason`	string \| null	Free-form reason e.g. `caller_hangup`, `agent_end`, `timeout`
`recording_url`	string \| null	Internal GCS path. Use `/audio` for a playable URL
`is_test_call`	boolean	True if the call is part of a test-calls run
`product`, `voice`	string	The Agent config in effect at call time
`billable_minutes`	integer \| null	Rounded-up minute count used for billing
`billing_total_cents`	integer \| null	Final bill in USD cents
`billed_at`	timestamp \| null	When billing finalised
`grade_score`	number \| null	0.0–1.0 quality score from latest AI grading
`grade_status`	string \| null	`pending`, `completed`, or `failed`
`grade_updated_at`	timestamp \| null	Last grading run
`issue_count`	integer	Total issue reports filed against this call
`critical_issue_count`	integer	Subset with severity `critical`

List calls

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

Query parameters

Param	Type	Default	Description
`limit`	integer	50	Page size (1–200)
`offset`	integer	0
`agent_id`	integer		Filter by agent
`direction`	string		`inbound`, `outbound`, `mic`, `widget`
`status`	string		`in_progress`, `completed`, `failed`
`from_number`	string		E.164
`to_number`	string		E.164
`start_date`	ISO 8601		Earliest `start_time`
`end_date`	ISO 8601		Latest `start_time`

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.

Export calls

Bulk-download up to 1,000 of the most recent completed calls as either CSV (metadata only) or JSON (includes transcripts).

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

Query param	Required	Description
`export_format`	yes	`csv` or `json`

The response includes a Content-Disposition: attachment header with a dated filename (calls-export-YYYY-MM-DD.csv). Exports cap at 1,000 rows — use the list endpoint with offset pagination for larger windows.

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.

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"

Response

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

Status	Condition
`200`	Recording exists, URL returned
`404`	Call or recording not found

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"

Response

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

Field	Type	Description
`role`	string	`user`, `assistant`, `tool_call`, or `tool_response`
`content_type`	string	`text`, `function`, or `function_response`
`content`	string	Human-readable content
`start_ms`, `end_ms`	integer	Offset from call start in milliseconds

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"

Response

{
  "id": 88,
  "call_id": 987654321,
  "score": 0.92,
  "call_outcome": "successful",
  "summary": "Caller asked about their policy and got a full answer…",
  "detected_issues": [],
  "status": "completed",
  "created_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

Trigger an asynchronous re-grade of the call. Pass force=true to ignore recent grades and re-run unconditionally.

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

Returns 200 OK with the grade row in status="pending" — poll the GET endpoint until status="completed" (usually under 30 s).

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"
  }'

Field	Type	Required	Allowed values
`title`	string	yes	1–120 chars
`description`	string	no	Free-form
`severity`	string	yes	`info`, `warning`, `critical`

Returns 201 Created with the Issue Report object.

Outbound Calls

Trigger a new outbound call via POST /v1/call.

Mic Sessions

Test an agent live from a browser.

Issue Reports

Org-wide feed of issue reports across calls.

Test Calls

Programmatic batched smoke tests against an agent.

Overview

Organizations

Agents

Phone Numbers

Billing

Developer

Calls

Endpoints

Call object

List calls

Query parameters

Paginated response

Export calls

Retrieve a call

Get recording audio

Get transcript

Get history

AI call grading

Get latest grade

Run grading

Issue reports

List reports for a call

File a report

Outbound Calls

Mic Sessions

Issue Reports

Test Calls

Overview

Organizations

Agents

Phone Numbers

Calls

Billing

Developer

​Endpoints

​Call object

​List calls

​Query parameters

​Paginated response

​Export calls

​Retrieve a call

​Get recording audio

​Get transcript

​Get history

​AI call grading

​Get latest grade

​Run grading

​Issue reports

​List reports for a call

​File a report

​Related

Outbound Calls

Mic Sessions

Issue Reports

Test Calls

Endpoints

Call object

List calls

Query parameters

Paginated response

Export calls

Retrieve a call

Get recording audio

Get transcript

Get history

AI call grading

Get latest grade

Run grading

Issue reports

List reports for a call

File a report

Related