Retrieve a call

GET

/v1/calls/{call_id}

const url = 'https://api.talki.it/v1/calls/example';
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/example \
  --header 'Authorization: Bearer <token>'

Return one call belonging to the authenticated account. Requires calls:read. A missing or cross-account ID returns the same 404 response.

Authorizations

ApiKeyAuth

Parameters

Path Parameters

call_id

required

Call Id

string

Responses

200

Successful Response

application/json

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

Example

{
  "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"
}

Headers

X-Request-Id

string

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.

404

No call with this ID exists in the authenticated account.

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": "resource_not_found",
    "message": "No such call.",
    "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.