API OverviewSessions & Calls

List sessions

View as Markdown
List the app's [sessions](/api/sessions), ordered from newest to oldest by `created_at`. The optional filters are combined, so a session must match every supplied filter. The endpoint does not use pagination. It returns all matching sessions when `limit` is omitted. When `limit` is set, it caps the number of filtered sessions returned, and `has_more` indicates whether additional matches exist.

Authentication

AuthorizationBearer
Application auth. Send `Authorization: Bearer <app_uuid>:<api_key>` using any active key in the app's collection. See [Authentication](https://voice-platform.docs.buildwithfern.com/api/authentication) for details.

Query parameters

limitintegerOptional>=1

Optional cap on the number of sessions to return. Omit to return every matching session; when set, at most this many are returned and has_more indicates whether more matched. A non-positive value returns 400.

caller_idstringOptionalformat: "^\+[1-9]\d{1,14}$"

Filter to sessions whose caller exactly matches this canonical E.164 value. The schema validates country-neutral syntax only; this historical-data filter does not apply current trunk policy.

didstringOptionalformat: "^\+[1-9]\d{1,14}$"

Filter to sessions whose called DID exactly matches this canonical E.164 value. The schema validates country-neutral syntax only; this historical-data filter does not apply current trunk policy.

stateenumOptional

Filter to sessions in this lifecycle state. Any other value returns 400.

created_afterdatetimeOptional

Inclusive lower bound on created_at (RFC 3339 UTC string). Only sessions created at or after this instant are returned. An invalid RFC 3339 value returns 400.

created_beforedatetimeOptional

Exclusive upper bound on created_at (RFC 3339 UTC string). Only sessions created strictly before this instant are returned. An invalid RFC 3339 value returns 400.

Response

The matching sessions.
has_moreboolean
True when more sessions matched than were returned.
sessionslist of objects

Errors

400
Bad Request Error
401
Unauthorized Error
413
Content Too Large Error
429
Too Many Requests Error
500
Internal Server Error