Skip to main content
GET
List Calls
Read only
Recommended. This endpoint is part of the public /v1 API reference and is the supported path for new integrations. See the migration guide for versioning guidance.
Returns every call placed in your workspace, paginated and sorted by start time (newest first). Each entry includes the call’s id, current status, agent_id, destination phone number, duration, and creation timestamp. Use this endpoint for lightweight call browsing, status polling against a known set of recent calls, and quick filtering by agent, call id, batch call id, outcome, or time range. ID filters support comma-separated multi-value input. For richer per-call data, full transcripts, recording URLs, sentiment, and the structured post-call analysis fields configured on the agent, use List Call Logs instead. Call logs carry the analytics payload while /calls is the lightweight scheduling-layer view.

When to use this

  • Operational dashboards: render a recent-calls table without paying the cost of full transcripts.
  • Live monitoring: quickly filter to initiated and in-progress calls to see active conversations.
  • Per-agent health checks: filter by agent_id to spot agents producing unusually high failure rates.
  • Batch exports: pass batch_call_id with export=true to download a combined CSV for one or more batches.

Query parameters

Errors

  • 400 Bad Request is returned when one or more query parameters are invalid.
  • 401 Unauthorized is returned when the API key is missing or invalid.
  • 403 Forbidden is returned when the API key does not have access to this organization.
  • 500 Internal Server Error is returned on an unexpected server-side failure.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

agent_id
string

Filter by agent ID(s) - can be a single ID or comma-separated list (e.g., 1,2,3)

call_id
string

Filter by call ID - can be a single ID or comma-separated list (e.g., call_abc,call_def)

batch_call_id
string

Filter by batch call ID - can be a single ID or comma-separated list (e.g., batch_abc,batch_def)

from
string

Filter by sender phone number

to
string

Filter by recipient phone number

type
enum<string>

Filter by call type(s) - can be a single value or comma-separated list

Available options:
phone,
web
call_direction
enum<string>

Filter by call direction(s) - can be a single value or comma-separated list

Available options:
inbound,
outbound
latency_min
number

Filter by minimum latency (in milliseconds)

latency_max
number

Filter by maximum latency (in milliseconds)

agent_version_id
string

Filter by agent version ID(s) - can be a single ID or comma-separated list (e.g., 1,2,3)

agent_version_name
string

Search by agent version name (partial match, case-insensitive)

sentiment
enum<string>

Filter by sentiment(s) - can be a single value or comma-separated list

Available options:
positive,
neutral,
negative,
unknown
start_date
string

Filter by start date (ISO format)

end_date
string

Filter by end date (ISO format)

duration_greater_than
number

Filter by minimum call duration (in milliseconds)

duration_less_than
number

Filter by maximum call duration (in milliseconds)

duration_min
number

Filter by minimum duration range (in milliseconds)

duration_max
number

Filter by maximum duration range (in milliseconds)

page
string

Page number (starts from 1)

limit
string

Number of records per page (min: 1, default: 20, max: 200)

created_at
enum<string>

Sort by created_at (asc or desc)

Available options:
asc,
desc
duration
enum<string>

Sort by duration (asc or desc)

Available options:
asc,
desc
status
string

Filter by call status(es) - can be a single status or comma-separated list

export
boolean

Set to true to export all data without pagination

end_reason
string

Filter by end/hangup reason - exact match; comma-separate multiple values for OR filtering

Response

Calls returned successfully.

id
string
required

Signed call ID

Example:

"call_abc123"