curl -X GET 'https://api.orbit.devotel.io/usage/cdr?from=2026-08-01T00:00:00Z&until=2026-08-02T00:00:00Z&include_unpriced=true&limit=1000' \
  -H 'X-API-Key: dv_live_sk_your_key_here'

{
  "data": {
    "range": { "from": "2026-08-01T00:00:00Z", "until": "2026-08-02T00:00:00Z" },
    "data": [
      {
        "id": "msg_01K0SXR3…",
        "type": "message",
        "channel": "sms",
        "direction": "outbound",
        "from_addr": "+15550001111",
        "to_addr": "+15559990000",
        "status": "delivered",
        "segments": 2,
        "duration_seconds": null,
        "price": "0.0123",
        "currency": "USD",
        "recorded_at": "2026-08-01T12:00:00.000Z",
        "sent_at": "2026-08-01T11:59:58.000Z",
        "delivered_at": "2026-08-01T12:00:01.000Z",
        "failed_at": null,
        "started_at": null,
        "answered_at": null,
        "ended_at": null,
        "sip_response_code": null,
        "error_code": null,
        "error_message": null,
        "contact_id": "cont_9J2…",
        "campaign_id": "camp_4RA…",
        "href": "/messages?id=msg_01K0SXR3…"
      },
      {
        "id": "call_0HX8…",
        "type": "call",
        "channel": "voice",
        "direction": "outbound",
        "from_addr": "+15550001111",
        "to_addr": "+15558880222",
        "status": "completed",
        "segments": null,
        "duration_seconds": 187,
        "price": "0.0300",
        "currency": "USD",
        "recorded_at": "2026-08-01T12:02:08.000Z",
        "sent_at": null,
        "delivered_at": null,
        "failed_at": null,
        "started_at": "2026-08-01T11:59:00.000Z",
        "answered_at": "2026-08-01T11:59:01.000Z",
        "ended_at": "2026-08-01T12:02:08.000Z",
        "sip_response_code": 200,
        "error_code": null,
        "error_message": null,
        "contact_id": "cont_9J2…",
        "campaign_id": null,
        "href": "/voice/calls/call_0HX8…"
      }
    ],
    "pagination": { "cursor": "MjAyNi0wOC0wMVQxMTowMDowMC4wMDBafGNhbGxfOWc=", "has_more": true }
  },
  "meta": { "request_id": "req_cdr_001", "timestamp": "2026-08-02T00:00:03Z" }
}

CDR Export & Billing Reconciliation API

Every finished message (SMS, MMS, WhatsApp, email, RCS, …) and every finished call in your workspace is recorded with the exact unit it was billed on — SMS segments, voice duration_seconds, the persisted price + currency the wallet was charged at send or call-close time, and terminal timestamps. This surface returns those records as one flat, recency-ordered feed you filter, page, and export. Use it to reconcile delivered usage against the billed record row-for-row. Reporting only: the feed never re-rates a record, never mutates a wallet, and never touches a provider. Base path: /usage Authentication: An organization API key (sent as X-API-Key or Authorization: Bearer dv_live_sk_…), or a session JWT for dashboard integrations. Either way, the caller must hold an owner, admin, or developer role with the billing:read scope — this feed is bulk billing data over the whole workspace, so both gates apply on both endpoints.

Export a JSON page

Page through CDRs

GET /usage/cdr Returns one page of records, newest first, scoped to the calling tenant. Filtered with the same query string as the CSV export below, so the two formats always agree on which rows match.

Query parameters

Field	Type	Notes
`from`	ISO-8601 string	Start of the window (inclusive). Defaults to 24 hours ago
`until`	ISO-8601 string	End of the window (exclusive). Defaults to now
`types`	CSV string	Restrict to `message`, `call`, or both. Unrecognised tokens are dropped, so a stale value never errors the export
`channels`	CSV string	Filter message channels (`sms`, `whatsapp`, `email`, …). Calls carry the synthetic channel `voice`, so `channels=voice` selects the calls arm
`statuses`	CSV string	One key spans both record kinds: message statuses (`queued`/`sent`/`delivered`/`failed`/…) and call statuses (`initiated`/`answered`/`completed`/`failed`/…)
`direction`	string	`inbound` or `outbound`
`include_unpriced`	string	`true` (default) keeps records whose `price` is NULL — a row that failed to rate still shows up. Pass `false` for billed-records-only
`cursor`	string	Opaque continuation token from a previous response’s `pagination.cursor`
`limit`	integer	Rows per page, 1–50,000 (default 10,000)

Row fields

Every row carries the billing and ops fields needed for line-level reconciliation — endpoints, statuses, prices, never free-text message bodies:

Field	Type	Notes
`id`	string	Message or call record id
`type`	string	`message` or `call`
`channel`	string	Message channel, or `voice` for calls
`direction`	string	`inbound` or `outbound`
`from_addr` / `to_addr`	string	Endpoints
`status`	string	Terminal status
`segments`	number	Billed SMS segments (null on calls)
`duration_seconds`	number	Billed call duration (null on messages)
`price`	string	The persisted charge as written at send/call-close
`currency`	string	ISO-4217 currency of the charge
`recorded_at`	ISO-8601 string	Recency key — created-at for messages, end-of-call for calls
`sent_at` / `delivered_at` / `failed_at`	ISO-8601 string	Message terminal timestamps (null on calls)
`started_at` / `answered_at` / `ended_at`	ISO-8601 string	Call billability timestamps (null on messages)
`sip_response_code`	number	Call SIP response code, when available
`error_code` / `error_message`	string	Failure details for the failed arm
`contact_id`	string	Attributed contact, when linked
`campaign_id`	string	Attributed campaign, when linked
`href`	string	Dashboard deep link to the record

curl -X GET 'https://api.orbit.devotel.io/usage/cdr?from=2026-08-01T00:00:00Z&until=2026-08-02T00:00:00Z&include_unpriced=true&limit=1000' \
  -H 'X-API-Key: dv_live_sk_your_key_here'

{
  "data": {
    "range": { "from": "2026-08-01T00:00:00Z", "until": "2026-08-02T00:00:00Z" },
    "data": [
      {
        "id": "msg_01K0SXR3…",
        "type": "message",
        "channel": "sms",
        "direction": "outbound",
        "from_addr": "+15550001111",
        "to_addr": "+15559990000",
        "status": "delivered",
        "segments": 2,
        "duration_seconds": null,
        "price": "0.0123",
        "currency": "USD",
        "recorded_at": "2026-08-01T12:00:00.000Z",
        "sent_at": "2026-08-01T11:59:58.000Z",
        "delivered_at": "2026-08-01T12:00:01.000Z",
        "failed_at": null,
        "started_at": null,
        "answered_at": null,
        "ended_at": null,
        "sip_response_code": null,
        "error_code": null,
        "error_message": null,
        "contact_id": "cont_9J2…",
        "campaign_id": "camp_4RA…",
        "href": "/messages?id=msg_01K0SXR3…"
      },
      {
        "id": "call_0HX8…",
        "type": "call",
        "channel": "voice",
        "direction": "outbound",
        "from_addr": "+15550001111",
        "to_addr": "+15558880222",
        "status": "completed",
        "segments": null,
        "duration_seconds": 187,
        "price": "0.0300",
        "currency": "USD",
        "recorded_at": "2026-08-01T12:02:08.000Z",
        "sent_at": null,
        "delivered_at": null,
        "failed_at": null,
        "started_at": "2026-08-01T11:59:00.000Z",
        "answered_at": "2026-08-01T11:59:01.000Z",
        "ended_at": "2026-08-01T12:02:08.000Z",
        "sip_response_code": 200,
        "error_code": null,
        "error_message": null,
        "contact_id": "cont_9J2…",
        "campaign_id": null,
        "href": "/voice/calls/call_0HX8…"
      }
    ],
    "pagination": { "cursor": "MjAyNi0wOC0wMVQxMTowMDowMC4wMDBafGNhbGxfOWc=", "has_more": true }
  },
  "meta": { "request_id": "req_cdr_001", "timestamp": "2026-08-02T00:00:03Z" }
}

Page forward by passing the opaque pagination.cursor from each response as the cursor query parameter. A malformed cursor degrades to the first page of the window rather than an error.

Export a CSV file

Download CDRs as CSV

GET /usage/cdr/export.csv The same filter set as the JSON feed, returned as a downloadable CSV attachment. Rate-limited to 5 requests per minute and capped at 50,000 rows per pull; page through the JSON endpoint for larger windows.

Additional query parameters

Field	Type	Notes
`filename`	string	Download filename stem, sanitized server-side

Every export is audit-logged as usage.cdr_exported with the row count, window, and truncation flag.

curl -X GET 'https://api.orbit.devotel.io/usage/cdr/export.csv?types=message&channels=sms,whatsapp&filename=august-usage' \
  -H 'X-API-Key: dv_live_sk_your_key_here' \
  -O

id,type,channel,direction,from_addr,to_addr,status,segments,duration_seconds,price,currency,recorded_at,sent_at,delivered_at,failed_at,started_at,answered_at,ended_at,sip_response_code,error_code,error_message,contact_id,campaign_id,href
msg_01K0SXR3VQ9JSTD6B6DZ0QJXM6,message,sms,outbound,+15550001111,+15559990000,delivered,2,,0.0123,USD,2026-08-01T12:00:00.000Z,2026-08-01T11:59:58.000Z,2026-08-01T12:00:01.000Z,,,,,,,,cont_9J2WYA,camp_4RAKZ,/messages?id=msg_01K0SXR3VQ9JSTD6B6DZ0QJXM6

When a pull exceeds the per-page cap, the response sets X-Export-Truncated: true — page through with the JSON endpoint to drain the window.

API Reference

All Endpoints

CDR Export API: per-call and per-message billing reconciliation feed

CDR Export & Billing Reconciliation API

Export a JSON page

Page through CDRs

Query parameters

Row fields

Export a CSV file

Download CDRs as CSV

Additional query parameters

​CDR Export & Billing Reconciliation API

​Export a JSON page

​Page through CDRs

​Query parameters

​Row fields

​Export a CSV file

​Download CDRs as CSV

​Additional query parameters

CDR Export & Billing Reconciliation API

Export a JSON page

Page through CDRs

Query parameters

Row fields

Export a CSV file

Download CDRs as CSV

Additional query parameters