List AI phone calls
Returns AI phone calls — outbound calls you placed and inbound calls your numbers answered (see direction) — most recent first, as a { object: "list", data } array.
Returns AI phone calls — outbound calls you placed and inbound calls your numbers answered (see direction) — most recent first, as a { object: "list", data } array. Filter with status (an exact lifecycle value such as in_progress or completed) and to (a destination number in E.164); limit accepts 1–100 and defaults to 50. This endpoint is not cursor-paginated — it returns the most recent matching calls up to limit. Requires the phone:read scope.
Scope: phone:read. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
status | string | no | Filter by call status. |
to | string | no | Filter by destination number (E.164). |
limit | integer | no | Maximum results (1-100). Defaults to 50. (minimum 1, maximum 100) |
Response
200 Success. Body: application/json, PhoneCallListResponse.
| Field | Type | Required | Description |
|---|---|---|---|
object | "list" | yes | |
data | array of PhoneCall | yes |
Errors
Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.
| Status | Meaning |
|---|---|
400 | The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch). |
401 | The API key is missing or invalid. |
403 | The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted). |
404 | No such resource in this account (resource_not_found). |
429 | Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached). |
500 | An unexpected error; retry with backoff, then contact support (internal_error). |
List the phone voices
Returns the phone voice catalog — the 22 Dairo Live voices you can pass as voice on POST /v1/phone/calls or inboundVoice on a number — as a { object: "list", kind: "phone", data } array.
Place an outbound AI phone call
Places an outbound AI voice call and returns immediately with the call in queued status; the dial runs asynchronously, so poll GET /v1/phone/calls/{id} or subscribe to call.status_changed to follow it to a terminal state.