​

CDR usage export for billing reconciliation

• GET /usage/cdr — one page of records as JSON, keyset-paginated.
• GET /usage/cdr/export.csv — the same filter set as a downloadable CSV.

​

1. Why a reconciliation feed

​

2. Two consumption modes

​

3. Query field matrix

• An unrecognised types, channels, or statuses token is dropped — it matches nothing, it never errors the request. A stale or typo’d value returns fewer rows, not a 422.
• until must be after from; otherwise the request 422s.
• include_unpriced defaults to true because a reconciliation feed that silently drops un-priced rows looks like “no usage” — you want the row to reconcile, even when its price is NULL.

​

4. Cursor-pagination walkthrough

FROM="2026-08-01T00:00:00Z"
UNTIL="2026-09-01T00:00:00Z"
CURSOR=""

while :; do
  URL="https://api.orbit.devotel.io/api/v1/usage/cdr?from=${FROM}&until=${UNTIL}&limit=10000"
  [ -n "$CURSOR" ] && URL="${URL}&cursor=${CURSOR}"

  RESP=$(curl -s "$URL" -H "X-API-Key: dv_live_sk_your_key_here")
  echo "$RESP" | jq -r '.data.data[] | [.id, .type, .status, .price, .currency] | @csv'

  HAS_MORE=$(echo "$RESP" | jq -r '.data.pagination.has_more')
  [ "$HAS_MORE" = "true" ] || break
  CURSOR=$(echo "$RESP" | jq -r '.data.pagination.cursor')
done

• data.range — the window this page covers (from / until).
• data.data — the rows, newest first.
• data.pagination.cursor — pass back as cursor on the next request.
• data.pagination.has_more — when false, the drain is done.

• A malformed or tampered cursor degrades to the first page of the window rather than erroring — an export surface doesn’t hard-fail on a bad token. Your loop should detect a repeated first-page id sequence and stop rather than drain the window twice.
• The cursor is tenant-bound and route-bound. A cursor from /usage/cdr is not exchangeable with the CSV endpoint’s continuation, and a cursor from one tenant is meaningless on another.

​

5. CSV layout and delivery

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

• Rate limit — 5 requests per minute. Treat a 429 as backoff, not failure (see Task 2 for the retry loop).
• Row cap — 50,000 rows per pull. When the window exceeds the cap, the response carries X-Export-Truncated: true and the file holds the first 50,000 rows of your window. Drain the rest through the JSON endpoint (section 4) — there’s no CSV-side continuation.
• Filter fidelity — the CSV applies the exact filter set you sent: the same window, the same channels, the same statuses. It’s never “the full month re-filtered client-side.” Export per-channel slices separately when finance wants per-channel CSVs; don’t export everything and filter downstream.
• Dedupe on rerun — rerunning an export with the same window and filters returns the same rows the window now resolves to. It is not a frozen snapshot: records that finished rating between your two runs appear in the second, and records that were pending in the first may now carry delivery timestamps. For close, treat the last re-export before your ledger freeze as authoritative. The row id is the dedupe key when you merge overlapping windows into a warehouse table.
• Audit log — every export is written to the audit log as usage.cdr_exported with the row count, window, and truncation flag, so the org has a record of who pulled billing data and when.

​

6. Worked reconciliation example

curl "https://api.orbit.devotel.io/api/v1/usage/cdr/export.csv?from=2026-08-01T00:00:00Z&until=2026-09-01T00:00:00Z&include_unpriced=true&filename=august-cdr" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -O

import csv
from collections import defaultdict
from decimal import Decimal

totals = defaultdict(Decimal)
with open("august-cdr-2026-09-01.csv") as f:
    for row in csv.DictReader(f):
        if row["price"] == "":
            bucket = (row["currency"] or "unpriced", row["type"], row["channel"])
            # keep unpriced rows visible — they're a separate bucket, not absent
            totals[bucket] += Decimal(0)
            continue
        bucket = (row["currency"], row["type"], row["channel"])
        totals[bucket] += Decimal(row["price"])

for (currency, kind, channel), total in sorted(totals.items()):
    print(f"{currency} {kind:8s} {channel:10s} {total}")

​

7. Caveats

• Rounding. The feed sums each record’s persisted price exactly; an invoice may round per line-item or aggregate at a different precision. Expect a sub-cent or few-cent variance per bucket — the deterministic shape from step 3 — and treat it as expected, not a discrepancy. If finance’s materiality threshold is tighter than per-line rounding, reconcile at the record level rather than the bucket level and the rounding variance collapses to nil.
• Time zones. from and until are ISO-8601 and compared in UTC — pass them with an explicit Z or offset. A window given in local time without offset lands where the server interprets it, which for a month-end close usually means a few hours of the wrong month on one side. Invoice periods are UTC-bounded too, so match the window to the invoice period exactly.
• Subaccount inheritance. The feed is scoped to the calling tenant. If your workspace operates subaccounts, run the export once per subaccount (with that subaccount’s key) and reconcile per-tenant; the parent tenant’s feed does not include child-tenant records. Aggregate the per-tenant CSVs client-side when finance wants one rolled-up file.
• Terminal status lag. A delivered message’s price is persisted at send, but its delivered_at may fill in after the fact. Export close to the period end and treat the last few minutes of the window as provisional — or re-export once before freezing the ledger (section 5).