Skip to main content

Calls

List calls

Returns the calls your API key can access, newest first. A key scoped to All agents returns calls from every agent in your company; a key scoped to Specific agents returns only calls handled by the agents linked to that key.

Authentication​

AuthorizationBearer

Authenticate server-side requests with a Fonema API key. Create one in the API keys section of the Dashboard and send it in the Authorization header as Bearer <token>. Keep keys out of client-side code and public repositories.

Query parameters​

pageintegerOptionalDefaults to 1

Page number to retrieve (1-based). Values below 1 fall back to 1.

limitintegerOptionalDefaults to 20

Number of calls per page. Maximum 100.

agentstringOptional

Only return calls handled by the agent with this slug. Returns 404 if the slug doesn't exist or isn't accessible by this key.

startDatestringOptional

Only return calls created on or after this date (ISO 8601, e.g. 2026-08-01). Must be sent together with endDate.

endDatestringOptional

Only return calls created on or before this date (ISO 8601). Must be sent together with startDate.

Response​

totalinteger
Total number of calls matching the query.
limitinteger
Page size used for this response.
offsetinteger
Number of calls skipped before this page.
currentPageinteger
The page returned.
totalPagesinteger
Total number of pages available.
callsarray
List of calls, newest first.
calls[].uidstring

Unique call identifier. Use it with Get call.

calls[].agentobject
The agent that handled the call (name and slug).
calls[].toNumberstring
Phone number that was called, in E.164 format.
calls[].endedReasonstring
Why the call ended (e.g. customer-ended-call, voicemail).
calls[].createdAtstring
When the call was created (queued).
calls[].startAtstring | null
When the call was answered. null if it never connected.
calls[].endAtstring | null
When the call ended.
calls[].durationSecondsinteger
Call duration in seconds. 0 if the call never connected.
calls[].successEvaluationboolean
Whether the call met the agent's success criteria.
calls[].inputDataobject

The variables provided when the call was created (e.g. via Start a call).

tip

Use the uid returned here as the identifier for Get call requests.

Errors​

404
The agent slug doesn't exist or isn't accessible by this API key.