List call history

list call history. The same records the Call History page shows, newest first by started_at, with offset-based pagination and resolved agent and contact names.

GET https://api.centerfy.ai/webhooks/inbound/calls

Headers

Header	Required	Value	Description
`x-api-key`	Yes	your sub-account API key (cfy_…)	authenticates the request; or pass Authorization: Bearer `<key>`.

Query parameters

Name	Type	Required	Default	Description
`limit`	`integer`	No	`50`	page size; min 1, max 100 (values above 100 are clamped to 100). Defaults to 50 when omitted or invalid.
`offset`	`integer`	No	`0`	number of rows to skip for pagination; min 0. Defaults to 0.
`from`	`string`	No	—	optional lower bound on started_at; ISO 8601 (include a UTC offset or Z). An invalid value returns 400.
`to`	`string`	No	—	optional upper bound on started_at; ISO 8601 (include a UTC offset or Z). A date-only value (no time) covers the whole day (through 23:59:59.999). An invalid value returns 400.
`status`	`string`	No	—	optional filter by call status (e.g. completed, no_answer, failed). Case-insensitive.
`direction`	`string`	No	—	optional filter by call direction; must be ‘inbound’ or ‘outbound’ (case-insensitive). Any other value returns 400.
`agent_id`	`string`	No	—	optional filter by AI agent id; must be a valid uuid or returns 400.

Example

curl -X GET "https://api.centerfy.ai/webhooks/inbound/calls?limit=50&offset=0" \
  -H "x-api-key: $CENTERFY_API_KEY"

import { CenterfyClient } from "@centerfy/sdk";

const centerfy = new CenterfyClient({ apiKey: process.env.CENTERFY_API_KEY! });

const result = await centerfy.calls.list({
  "limit": 50,
  "offset": 0
});
console.log(result);

centerfy calls list '{"limit":50,"offset":0}'

MCP tool: centerfy_calls_list (see MCP server)

Response

{
  "status": "success",
  "total": 342,
  "limit": 50,
  "offset": 0,
  "has_more": true,
  "calls": [
    {
      "id": "d4e5f6a7-2222-4abc-9def-000000000020",
      "call_sid": "CA0123456789abcdef0123456789abcdef",
      "direction": "inbound",
      "status": "completed",
      "from": "+14155550123",
      "to": "+18005551234",
      "duration_seconds": 142,
      "has_recording": true,
      "agent_id": "b2c3d4e5-3333-4abc-9def-000000000030",
      "agent_name": "Front Desk AI",
      "contact_id": "7f1c9e2a-3b4d-4e5f-8a90-1b2c3d4e5f60",
      "contact_name": "Jane Doe",
      "ended_reason": "completed",
      "started_at": "2026-06-12T15:00:00.000Z",
      "ended_at": "2026-06-12T15:02:22.000Z"
    }
  ]
}

Errors

401 — if unauthenticated; 400 for an invalid from/to, an invalid direction, or a non-uuid agent_id.

Notes

Read-only. total is the exact count for the applied filters; has_more is true when offset + returned count < total. agent_name and contact_name are resolved where available (null if not found).