List calls

GET

/v1/calls

const url = 'https://api.talki.it/v1/calls?limit=50';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.talki.it/v1/calls?limit=50' \
  --header 'Authorization: Bearer <token>'

Return calls newest first, ordered by started_at and then id. Requires calls:read. Limited to 600 requests per minute per credential.

Authorizations

ApiKeyAuth

Parameters

Query Parameters

limit

Limit

Maximum number of calls to return.

integer

default: 50 >= 1 <= 100

Maximum number of calls to return.

cursor

Any of:

string
null

string

Opaque cursor from a previous response’s next_cursor. Omit for the first page.

created_after

Any of:

string
null

string format: date-time

Only calls recorded at or after this instant (RFC 3339 UTC). INCLUSIVE, so a watermark equal to a record’s created_at returns that record again rather than risking skipping it — dedupe on id. Filters on created_at, not started_at: see the note on Call.created_at. When resuming a sync, subtract a safety lag (a minute is ample) from your stored watermark: created_at is the writing transaction’s start time, so it is ordered but not strictly commit-ordered.

created_before

Any of:

string
null

string format: date-time

Only calls recorded strictly before this instant (RFC 3339 UTC).

Responses

200

Successful Response

application/json

CallList

object

data

required

Data

Array<object>

Call

One inbound call the assistant answered. Calls are immutable after they are written. The public object deliberately excludes LLM usage, dashboard inbox state, refused calls, verbatim transcripts, and audio.

object

required

Opaque Talki call identifier.

string

caller

required

CallCaller

Who called, as far as Talki can establish. The object is always present; its fields may be null. A display name is published only when the account owner curated it or imported it from an address book.

object

contact_id

required

Any of:

string
null

string

phone_number

required

Any of:

string
null

string

display_name

required

Any of:

string
null

string

started_at

required

Started At

When the call ARRIVED, before the assistant picked up. RFC 3339 UTC. This is the ordering key for GET /v1/calls.

string

answered_at

required

Any of:

string
null

string

ended_at

required

Any of:

string
null

string

duration_seconds

required

Any of:

integer
null

integer

summary

required

Any of:

string
null

string

appointment_ids

required

Appointment Ids

Appointments booked during this call, oldest first. Empty for a call that booked nothing. Includes appointments since cancelled — the link records what the call did, not the appointment’s current state.

Array<string>

created_at

required

Created At

When Talki wrote this record, which is after the call ended, not when the call started. This is the field created_after filters on, and the one to watermark an incremental sync against: a long call can be written AFTER a shorter call that started later, so a watermark on started_at could skip it.

string

next_cursor

Any of:

string
null

string

has_more

Has More

True when another page is available.

boolean

Example

{
  "data": [
    {
      "id": "38d23d84-02d2-4418-b169-3608aa04a8f8",
      "caller": {
        "contact_id": "8fbb25f2-4f3b-4496-8aea-f0fc66de512d",
        "phone_number": "+393331234567",
        "display_name": "Giulia Bianchi"
      },
      "started_at": "2026-09-15T09:14:31Z",
      "answered_at": "2026-09-15T09:14:34Z",
      "ended_at": "2026-09-15T09:18:02Z",
      "duration_seconds": 208,
      "summary": "Giulia asked to move her haircut to Friday morning.",
      "appointment_ids": [
        "a3fe45ee-572f-4677-b1dd-f36c21bb47de"
      ],
      "created_at": "2026-09-15T09:18:03Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Headers

X-Request-Id

string

Identifier to include when contacting Talki support.

400

A query parameter or cursor is invalid.

application/json

object

error

required

object

type

required

string

code

required

string

message

required

string

request_id

required

string

Example

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_parameter",
    "message": "limit: Input should be less than or equal to 100",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

X-Request-Id

string

Example

req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

401

The credential is missing, malformed, expired, revoked, or unknown.

application/json

object

error

required

object

type

required

string

code

required

string

message

required

string

request_id

required

string

Example

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credentials",
    "message": "The supplied API credential is invalid.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

X-Request-Id

string

Example

req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

403

The account or credential may not perform this request.

application/json

object

error

required

object

type

required

string

code

required

string

message

required

string

request_id

required

string

Example

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This credential does not have the required scope.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

X-Request-Id

string

Example

req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

429

The credential exceeded its request rate.

application/json

object

error

required

object

type

required

string

code

required

string

message

required

string

request_id

required

string

Example

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after the interval in Retry-After.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

X-Request-Id

string

Example

req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.

500

An unexpected error occurred.

application/json

object

error

required

object

type

required

string

code

required

string

message

required

string

request_id

required

string

Example

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected error occurred. Quote the request_id when reporting it.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

Headers

X-Request-Id

string

Example

req_7f24a2f8c6b64e699901563a458b5031

Identifier to include when contacting Talki support.