List calls

GET /api/v1/calls

Paginated list of calls. Every call placed via phone, WebSocket, or WebRTC lands here. Use the filters to narrow by transport, status, agent, time window, source, or tag.

Authentication

X-API-Key: zsk_...

Query parameters

Pagination & sort

ended_at sort puts NULLs last so in-flight calls don't crowd the top of the default view.

Filters

Response

Returns HTTP 200 OK with the standard paginated envelope.

{
  "items": [
    {
      "callId": "call_4e4e571f8c9b3cf8e99d",
      "transport": "outbound",
      "pipelineSource": "agent",
      "status": "completed",
      "connectionStatus": "completed",
      "endedReason": "user_hangup",
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "agentName": "Sales bot",
      "campaignId": null,
      "platformNumber": "+14155550100",
      "customerNumber": "+14155559999",
      "telephonyProvider": "twilio",
      "callSource": "api_outbound",
      "startedAt": "2026-06-16T10:30:12Z",
      "endedAt":   "2026-06-16T10:32:01Z",
      "durationSeconds": 109,
      "createdAt": "2026-06-16T10:30:10Z",
      "cost": 0.0185,
      "tags": ["api", "outbound"]
    }
  ],
  "total": 1234,
  "page": 1,
  "perPage": 50,
  "totalPages": 25
}

CallListItem fields

Examples

Last 24 hours of API-first outbound calls that never connected

FROM=$(date -u -v-1d +%Y-%m-%dT%H:%M:%SZ)
curl "https://dashboard.zoxa.ai/api/v1/calls?transport=outbound&call_source=api_outbound&connection_status=busy,no_answer,connection_failed,dial_failed&from_date=$FROM" \
  -H "X-API-Key: zsk_..."

const from = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
const params = new URLSearchParams({
  transport: "outbound",
  call_source: "api_outbound",
  connection_status: "busy,no_answer,connection_failed,dial_failed",
  from_date: from,
});
const res = await fetch(`https://dashboard.zoxa.ai/api/v1/calls?${params}`, {
  headers: { "X-API-Key": "zsk_..." },
});
const { items, total } = await res.json();

from datetime import datetime, timedelta, timezone
import httpx

frm = (datetime.now(timezone.utc) - timedelta(days=1)).isoformat()
resp = httpx.get(
    "https://dashboard.zoxa.ai/api/v1/calls",
    headers={"X-API-Key": "zsk_..."},
    params={
        "transport": "outbound",
        "call_source": "api_outbound",
        "connection_status": "busy,no_answer,connection_failed,dial_failed",
        "from_date": frm,
    },
)
data = resp.json()
print(data["total"], "not-connected calls in last 24h")

Connected calls that crashed mid-conversation

curl "https://dashboard.zoxa.ai/api/v1/calls?connection_status=completed&ended_reason=pipeline_error" \
  -H "X-API-Key: zsk_..."

Calls for one agent, paginated

curl "https://dashboard.zoxa.ai/api/v1/calls?agent_id=550e8400-...&per_page=100&page=2" \
  -H "X-API-Key: zsk_..."

Errors

The two outcome dimensions

Every call carries two orthogonal outcome fields:

• connectionStatus — did the call connect? completed when the callee answered (telephony) or the client joined (web); otherwise the reason it never connected — a telephony outcome, a platform failure, or an API rejection.
• endedReason — why did a connected call end? Only populated once the conversation actually started. Always null for calls that never connected.

                 ┌─ NOT CONNECTED → connectionStatus = why   |  endedReason = null
call attempt ────┤
                 └─ CONNECTED     → connectionStatus = "completed"  |  endedReason = why it ended

connectionStatus values

Telephony / transport outcomes

Platform failures (never dialed / never reached the provider)

API rejections (request never became a call)

Each rejection class is its own connectionStatus value, so one filter isolates one failure mode. See Rejected calls for how the raw request and rejection payload are preserved on the row.

endedReason values

Why a connected call ended. Exactly nine values — null until the call connects, and forever null for calls that never did (their outcome lives in connectionStatus).

Analytics buckets

Group on connectionStatus first, then split connected calls by endedReason:

• Success (conversation happened): connectionStatus=completed with endedReason in user_hangup, agent_hangup, silence_timeout, max_duration, voicemail, transferred, cancelled.
• Connected but crashed: connectionStatus=completed + endedReason=pipeline_error — the only connected ending that marks the row status=error.
• Connected, unattributed: connectionStatus=completed + endedReason=unknown — count it separately; a rising number means something isn't reporting its exit.
• Didn't connect (operational): connectionStatus in no_answer, busy, rejected, invalid_number, unreachable, cancelled, no_participant, telephony_<raw> — normal telephony attrition, tune your dialing instead of debugging.
• Didn't connect (platform failure): connection_failed, dial_failed, initiation_failed, missing_credentials — investigate.
• Rejected before start: the API-rejection values plus concurrency_limit_reached / insufficient_balance — fix the request or the account, not the call.

Rejected calls

Every authenticated request that's rejected before the pipeline starts — bad schema, unresolvable agent, invalid credentials, tool errors, and gate rejections (concurrency limit, insufficient wallet balance) — creates a row in this list. The row has status="error", the rejected tag, the rejection reason in connectionStatus (from the API rejections table above), and endedReason: null — the call never connected, so there is no conversation ending to report. The configSnapshot on the detail response is the redacted request body the client sent (auth scrubbed), and logs.validation_error carries the full rejection payload (Pydantic error tree, or the concurrency/wallet state frozen at rejection time).

Gate rejections (concurrency_limit_reached, insufficient_balance) are throttled to one row per org+reason per minute so a client retry loop can't flood the table — the first row of a burst carries everything needed.

Dial-leg failures are different: they produce a real call row (connectionStatus: dial_failed, callSource: api_outbound) whose logs.dial_error carries the provider's error message and providerStatus. The callId in the provider_rejected error response links straight to it.

This makes it possible to diagnose API integration issues without bouncing screenshots between two teams: pull the call by id, see exactly what arrived, and see exactly why we rejected it.

# All rejected attempts in the last day for one org
curl "https://dashboard.zoxa.ai/api/v1/calls?tag=rejected&from_date=$(date -u -v-1d +%FT%TZ)" \
  -H "X-API-Key: zsk_..."

Filter further with connection_status=schema_validation (or any of the rejection values above) to isolate one class.

Related

• GET /calls/{callId} — full detail incl. transcript, recordings, latency stats
• Campaign runs — per-call run list scoped to a campaign