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.

Endpoint

GET /v1/calls

Query parameters

Parameter	Type	Default	Description
page	integer	1	Page number to retrieve (1-based). Values below 1 fall back to 1.
limit	integer	20	Number of calls per page. Maximum 100.
agent	string	—	Optional. 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.
startDate	string	—	Optional. Only return calls created on or after this date (ISO 8601, e.g. 2026-08-01). Must be sent together with endDate.
endDate	string	—	Optional. Only return calls created on or before this date (ISO 8601). Must be sent together with startDate.

Request example

curl -X GET "https://api.fonema.ai/v1/calls?page=1&limit=20&agent=sales-agent-ab12cd34" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"

Response

{
  "offset": 0,
  "total": 128,
  "limit": 20,
  "currentPage": 1,
  "totalPages": 7,
  "calls": [
    {
      "uid": "aBcDeFgHiJkL",
      "agent": { "name": "Sales Agent", "slug": "sales-agent-ab12cd34" },
      "toNumber": "+525599999999",
      "endedReason": "customer-ended-call",
      "createdAt": "2026-08-06T17:00:00.000Z",
      "startAt": "2026-08-06T17:00:05.000Z",
      "endAt": "2026-08-06T17:02:35.000Z",
      "durationSeconds": 150,
      "successEvaluation": true,
      "inputData": {
        "name": "Juan Perez",
        "montoDeuda": "30000"
      }
    }
  ]
}

Response fields

Field	Type	Description
total	integer	Total number of calls matching the query.
limit	integer	Page size used for this response.
offset	integer	Number of calls skipped before this page.
currentPage	integer	The page returned.
totalPages	integer	Total number of pages available.
calls	array	List of calls, newest first.
calls[].uid	string	Unique call identifier. Use it with Get call.
calls[].agent	object	The agent that handled the call (name and slug).
calls[].toNumber	string	Phone number that was called, in E.164 format.
calls[].endedReason	string	Why the call ended (e.g. customer-ended-call, voicemail).
calls[].createdAt	string	When the call was created (queued).
calls[].startAt	string | null	When the call was answered. null if it never connected.
calls[].endAt	string | null	When the call ended.
calls[].durationSeconds	integer	Call duration in seconds. 0 if the call never connected.
calls[].successEvaluation	boolean	Whether the call met the agent's success criteria.
calls[].inputData	object	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

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