Voice Call Logs

Voice call logging is essential for monitoring telecommunications activity and compliance requirements. On this page, we will dive into the voice call logging endpoints you can use to retrieve and analyze call records programmatically. We will look at how to fetch call logs with filtering, retrieve facet counts, and export records as CSV.

All voice log endpoints are scoped to your customer account via the {customer_slug} path segment and authenticate with an API key created in the portal under Settings → API Keys. Send the key either as Authorization: Bearer xn_... or in the X-API-Key header. The key must include the tenant:usage-logs:read permission.

The voice call log model

The voice call log model contains the information returned for each call record: participants, timing, duration, status, and cost. Phone numbers are stored as bare digits including the country code, with no leading + (e.g. 15551234567).

Properties

Name
call_id
Type
uuid
Description
Unique identifier for the voice call log entry.
Name
number_id
Type
uuid
Description
Identifier of the xNumbers number associated with the call (nullable).
Name
direction
Type
string
Description
Call direction: "inbound" or "outbound".
Name
from_number
Type
string
Description
The originating phone number (digits with country code, no leading "+").
Name
to_number
Type
string
Description
The destination phone number (digits with country code, no leading "+").
Name
start_time
Type
timestamp
Description
Call start timestamp.
Name
end_time
Type
timestamp
Description
Call end timestamp (nullable).
Name
duration_seconds
Type
integer
Description
Call duration in seconds.
Name
status
Type
string
Description
Call status: "completed", "failed", "busy", "no-answer", or "cancelled".
Name
cost
Type
string
Description
Calculated cost for the call as a decimal string (nullable).
Name
currency
Type
string
Description
Currency for the cost (nullable).
Name
created_at
Type
timestamp
Description
Record creation timestamp.

GET/customers/{customer_slug}/logs/voice

List voice call logs

This endpoint allows you to retrieve voice call logs for your customer account with filtering and pagination. By default, a maximum of ten records are shown per page, ordered by start_time.

Optional attributes

Name
page
Type
integer
Description
Page number for pagination (default: 1).
Name
limit
Type
integer
Description
Number of logs per page (default: 10).
Name
direction
Type
string
Description
Filter by call direction: "inbound" or "outbound". Multiple values can be passed comma-separated.
Name
status
Type
string
Description
Filter by call status: "completed", "failed", "busy", "no-answer", or "cancelled". Multiple values can be passed comma-separated.
Name
country_code
Type
string
Description
Filter by country code — exactly 2 uppercase letters (e.g. "US").
Name
date_from
Type
string
Description
Only include calls with start_time on or after this date (ISO 8601).
Name
date_to
Type
string
Description
Only include calls with start_time on or before this date (ISO 8601).
Name
search
Type
string
Description
Partial match against from_number and to_number (max 100 characters).
Name
sort_by
Type
string
Description
Accepted values: "start_time", "duration_seconds", "cost", "created_at" (default: "start_time"). Results are currently always ordered by start_time.
Name
sort_order
Type
string
Description
Sort direction on start_time: "asc" or "desc" (default: "desc").

Request

GET

/customers/{customer_slug}/logs/voice

curl -G https://api.xnumbers.io/api/customers/acme/logs/voice \
  -H "Authorization: Bearer xn_your_api_key" \
  -d page=1 \
  -d limit=10 \
  -d direction=inbound \
  -d date_from=2026-01-01 \
  -d sort_order=desc

Response

{
  "data": [
    {
      "call_id": "12345678-1234-1234-1234-123456789abc",
      "number_id": "87654321-4321-4321-4321-210987654321",
      "direction": "inbound",
      "from_number": "15551234567",
      "to_number": "12125551234",
      "start_time": "2026-01-15T10:30:00.000Z",
      "end_time": "2026-01-15T10:35:00.000Z",
      "duration_seconds": 300,
      "status": "completed",
      "cost": "0.1000",
      "currency": "USD",
      "created_at": "2026-01-15T10:35:30.000Z"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 10,
    "totalPages": 15
  }
}

GET/customers/{customer_slug}/logs/voice/facets

This endpoint returns facet counts for your voice call logs — the number of logs grouped by status and by direction across your whole account. It takes no query parameters and is useful for building filter UIs or dashboards.

Request

GET

/customers/{customer_slug}/logs/voice/facets

curl https://api.xnumbers.io/api/customers/acme/logs/voice/facets \
  -H "Authorization: Bearer xn_your_api_key"

Response

{
  "status": {
    "completed": 1250,
    "failed": 43,
    "busy": 12
  },
  "direction": {
    "inbound": 820,
    "outbound": 485
  }
}

GET/customers/{customer_slug}/logs/voice/export/csv

Export voice call logs

This endpoint allows you to export voice call logs as a CSV file. It supports the same filter parameters as the list endpoint (direction, status, country_code, date_from, date_to, search). Pagination parameters are ignored — the export contains up to 10,000 records matching your filters, ordered by start_time.

Export format

The CSV contains the columns: Start Time, From Number, To Number, Duration (seconds), Status, Direction, Provider, Number Type, Cost, Currency, Tariff.

Request

GET

/customers/{customer_slug}/logs/voice/export/csv

curl -G https://api.xnumbers.io/api/customers/acme/logs/voice/export/csv \
  -H "Authorization: Bearer xn_your_api_key" \
  -d direction=inbound \
  -d date_from=2026-01-01 \
  -d date_to=2026-01-31 \
  --output voice-logs.csv

Returns the CSV file as a download with the headers:

Content-Type: text/csv
Content-Disposition: attachment; filename="{customer_slug}-voice-logs-export-YYYY-MM-DD.csv"

Voice Call Logs

The voice call log model

Properties

List voice call logs

Optional attributes

Request

Response

Retrieve voice log facets

Request

Response

Export voice call logs

Export format

Request