---
title: "Read a Click2Call call"
method: GET
path: "/api/v1/click2call/{id}"
tags: ["Click2Call"]
---

# Read a Click2Call call

`GET /api/v1/click2call/{id}`

## Request

- Base URL: `https://app.didlogic.com`
- URL: `https://app.didlogic.com/api/v1/click2call/{id}`
- Auth: HTTP bearer

Returns the current state of one call. This is the polling endpoint: call it
until `state` is `completed` or `failed`.

### States

| State | Meaning |
|---|---|
| `accepted` | The call was placed; no leg has moved yet |
| `agent_ringing` | Your SIP account is ringing — **best-effort, may be skipped** |
| `agent_answered` | Your SIP account answered |
| `customer_ringing` | The destination is being dialled |
| `bridged` | Both legs are up and talking |
| `completed` | The call ended normally |
| `failed` | The call did not come together |

`agent_ringing` is derived from a ringing indication on the agent leg, which
some user agents never send. A call may therefore go straight from
`accepted` to `agent_answered`; clients must not require `agent_ringing`.

### `reason`

`reason` answers *why the call ended*, on its own axis from `state`. It is
`null` while the call is live **and** on a normal end. Otherwise it is one
of `no_answer`, `busy`, `unreachable`, `canceled`, `timed_out` or
`platform_error`. A call your own `DELETE` ended reports `canceled` —
including when it had already been answered, in which case `state` is
`completed`. A `DELETE` that arrives after the call has already ended leaves
the original reason in place.

### Retention

A call is readable for **12 hours from the moment it was placed** — not from
the moment it ended. After that the record is gone and this endpoint answers
`404`. Call history is a separate product surface.

### `404`

`404 call_not_found` means the call is unknown to you: it never existed, the
ID is malformed, it belongs to another account, or it has fallen out of the
12-hour window. The cases are deliberately indistinguishable.

`data.recording_url` feeds recordings_show. See also: click2call_destroy.

## Path parameters

- `id` string, required

## Response `200`

The current state of the call.

- object
  - `data` object, required: The Click2Call call resource
    - `id` string, required: Call ID (26-character ULID)
    - `state` 'accepted' | 'agent_ringing' | 'agent_answered' | 'customer_ringing' | 'bridged' | 'completed' | 'failed', required: How far the call got. `agent_ringing` may be skipped — see the description above.
    - `reason` 'no_answer' | 'busy' | 'unreachable' | 'canceled' | 'timed_out' | 'platform_error', nullable, required: Why the call ended. `null` while the call is live and on a normal end.
    - `a_type` string, required: Type of the agent leg. Always `sip_account` in v1.
    - `a_endpoint` string, required: The SIP account that was rung first
    - `b_number` string, required: Destination number, digits only
    - `b_cli` string, nullable, required: Always `null` in v1
    - `created_at` string, required: When the call was placed. The 12-hour retention window runs from here.
    - `agent_ringing_at` string, nullable, required: When the agent leg started ringing. Best-effort: `null` when the phone never reported the ring, not only when it never rang.
    - `agent_answered_at` string, nullable, required: When the agent leg answered
    - `customer_ringing_at` string, nullable, required: When the destination was dialled
    - `bridged_at` string, nullable, required: When the two legs were bridged
    - `ended_at` string, nullable, required: When the call ended
    - `duration` integer, nullable, required: Whole life of the call in seconds, ringing included. Not the billed time.
    - `cost` string, nullable, required: Total cost in dollars, four decimals
    - `finalized_at` string, nullable, required: When the billed record was committed. `null` until then, and until it is set `cost` may still be `null`.
    - `recording_url` string, nullable, required: Where the recording of the call can be downloaded. `null` when the call was not recorded, and `null` on a call that has not settled yet. By default the link is signed and expires one hour after it was minted; each read of the call mints a fresh one, and `GET /api/v1/calls/recording/{callid}` also gives one. If the account has permanent recording links enabled (on request through your account manager or support), the field holds a permanent `/api/v1/recordings/{user_id}/{token}` URL instead. It does not expire while the recording is retained and the option stays on.
    - `client_call_id` string, nullable, required: The label you supplied when placing the call, echoed back unchanged. `null` when none was supplied. Carried on every webhook for this call.
    - `a_cli` string, nullable, required: The caller ID the agent leg was presented with, digits only: the `a_cli` you supplied, or `b_number` when you supplied none. Carried on every webhook for this call.

## Other responses

- `401`: The API token is missing or incorrect. This endpoint answers `401`; the rest of v1 answers `403` for the same refusal.
- `403`: The API token is missing or incorrect, or the Click2Call API is not enabled for this account (`click2call_api_disabled`).
- `404`: No such call: it never existed, the ID is malformed, it belongs to another account, or it is older than the 12-hour retention window.

---

[API](https://skmtc.dev/didlogic/apis/get-started.md) · [All operations](https://skmtc.dev/didlogic/apis/get-started/llms.txt) · [OpenAPI document](https://skmtc.dev/didlogic/apis/get-started/revisions/dc972d592b34?raw)