---
title: "List call records"
method: GET
path: "/api/v1/calls"
tags: ["Call Records"]
---

# List call records

`GET /api/v1/calls`

## Request

- Base URL: `https://api.callnode.io`
- URL: `https://api.callnode.io/api/v1/calls`
- Auth: API key in header `X-Api-Key` and API key in header `X-Timestamp` and API key in header `X-Signature`

Records of calls on your numbers, newest first — the same rows the
dashboard's call history shows. Covers inbound calls (webhook-answered,
BYOC `voice.sipUri` deliveries, SIP-trunk ingress) and outbound calls
logged against your numbers.

`endReason` and `sipCause` say **why a call ended**: `endReason` is
CallNode's own vocabulary (for example `idle_timeout` or
`insufficient_balance`; null means an ordinary hangup), and `sipCause`
is the SIP-level hangup cause of the caller leg (for example
`NORMAL_CLEARING` or `RECOVERY_ON_TIMER_EXPIRE`). Records from before
2026-09-22 predate these fields and return null for both.

## Query parameters

- `number` string
- `direction` 'inbound' | 'outbound'
- `status` 'in_progress' | 'completed' | 'failed'
- `since` string, date-time
- `until` string, date-time
- `before` string, date-time
- `limit` integer

## Response `200`

Call records, newest first.

- object
  - `calls` CallRecord[]
    - `callId` string: The call's uuid — matches `X-CallNode-Call-Id` on BYOC INVITEs.
    - `direction` 'inbound' | 'outbound'
    - `from` string
    - `to` string
    - `number` string: The CallNode number (E.164) the record belongs to.
    - `status` 'in_progress' | 'completed' | 'failed'
    - `startTime` string, date-time
    - `endTime` string, date-time, nullable
    - `durationSecs` integer
    - `endReason` string, nullable: CallNode's reason the call ended. Null = ordinary hangup.
    - `sipCause` string, nullable: SIP-level hangup cause of the caller leg (e.g. NORMAL_CLEARING).
    - `errorMessage` string, nullable
    - `webhookErrors` integer
    - `sipTrunkId` string, nullable: Set when the call arrived over one of your SIP trunks.
    - `createdAt` string, date-time
  - `count` integer
  - `nextBefore` string, nullable: Pass as `before` to fetch older records. Null on the last page.

## Other responses

- `401`: Missing, unknown, or badly signed credentials — check the HMAC and the timestamp skew.
- `429`: Rate limit exceeded. See the rate-limit response headers.

---

[API](https://skmtc.dev/callnode/apis/callnode-outbound-api.md) · [All operations](https://skmtc.dev/callnode/apis/callnode-outbound-api/llms.txt) · [OpenAPI document](https://skmtc.dev/callnode/apis/callnode-outbound-api/revisions/c7da6ad06509?raw)