Analytics

Usage analytics and statistics are essential for monitoring telecommunications activity and performance analysis. On this page, we will dive into the different analytics endpoints you can use to track usage statistics and analyze communication data programmatically. All analytics endpoints live under /customers/{customer_slug}/analytics and are scoped to your own customer account.

All analytics endpoints are available with API keys. Authenticate by sending your key in the Authorization: Bearer xn_... header (alternatively, the X-API-Key header). You can create API keys in the portal under Settings → API Keys. Your key must carry the tenant:analytics:read permission.

The usage trend model

Several analytics endpoints return daily time series. Each data point in the usage trends series contains the date and the activity counters for that day.

Properties

Name
date
Type
string
Description
The day this data point covers, formatted as YYYY-MM-DD.
Name
voice_calls
Type
number
Description
Number of voice calls logged on this day.
Name
sms_count
Type
number
Description
Number of SMS messages logged on this day.

GET/customers/{customer_slug}/analytics/numbers/by-type

List numbers by type

This endpoint returns the count of your phone numbers grouped by number type (for example mobile or landline). It takes no query parameters.

Response properties

Name
number_type
Type
string
Description
The number type this group represents.
Name
count
Type
number
Description
How many of your numbers have this type.

Request

GET

/customers/acme/analytics/numbers/by-type

curl https://api.xnumbers.io/api/customers/acme/analytics/numbers/by-type \
  -H "Authorization: Bearer xn_your_api_key"

Response

[
  {
    "number_type": "mobile",
    "count": 120
  },
  {
    "number_type": "landline",
    "count": 35
  }
]

GET/customers/{customer_slug}/analytics/numbers/by-country

List numbers by country

This endpoint returns the count of your phone numbers grouped by country code. It takes no query parameters.

Response properties

Name
country_code
Type
string
Description
The ISO country code this group represents.
Name
count
Type
number
Description
How many of your numbers belong to this country.

Request

GET

/customers/acme/analytics/numbers/by-country

curl https://api.xnumbers.io/api/customers/acme/analytics/numbers/by-country \
  -H "Authorization: Bearer xn_your_api_key"

Response

[
  {
    "country_code": "US",
    "count": 98
  },
  {
    "country_code": "GB",
    "count": 57
  }
]

GET/customers/{customer_slug}/analytics/voice-calls/total

Get total voice calls

This endpoint returns the all-time total number of voice calls logged for your account. It takes no query parameters.

The response body is a plain JSON number — the total call count — not an object.

Request

GET

/customers/acme/analytics/voice-calls/total

curl https://api.xnumbers.io/api/customers/acme/analytics/voice-calls/total \
  -H "Authorization: Bearer xn_your_api_key"

Response

GET/customers/{customer_slug}/analytics/sms/total-this-month

Get total SMS this month

This endpoint returns the total number of SMS messages logged for your account during the current calendar month. It takes no query parameters.

The response body is a plain JSON number — the total message count — not an object.

Request

GET

/customers/acme/analytics/sms/total-this-month

curl https://api.xnumbers.io/api/customers/acme/analytics/sms/total-this-month \
  -H "Authorization: Bearer xn_your_api_key"

Response

GET/customers/{customer_slug}/analytics/usage-trends

Get usage trends

This endpoint returns a daily time series of voice call and SMS activity for the last 7 days. The window is fixed — the endpoint takes no query parameters. Days with no activity are included with zero counts.

Response properties

Name
date
Type
string
Description
The day this data point covers, formatted as YYYY-MM-DD.
Name
voice_calls
Type
number
Description
Number of voice calls logged on this day.
Name
sms_count
Type
number
Description
Number of SMS messages logged on this day.

Request

GET

/customers/acme/analytics/usage-trends

curl https://api.xnumbers.io/api/customers/acme/analytics/usage-trends \
  -H "Authorization: Bearer xn_your_api_key"

Response

[
  {
    "date": "2026-06-05",
    "voice_calls": 42,
    "sms_count": 110
  },
  {
    "date": "2026-06-06",
    "voice_calls": 0,
    "sms_count": 0
  },
  {
    "date": "2026-06-07",
    "voice_calls": 57,
    "sms_count": 134
  }
]

GET/customers/{customer_slug}/analytics/tariff-metrics

Get tariff metrics

This endpoint returns comprehensive tariff metrics for the current calendar month: NRC and MRC charges per active tariff, the per-unit usage rates of each tariff, and a summary of your voice and SMS usage. The period is always the current month — the endpoint takes no query parameters.

Response properties

Name
period
Type
object
Description
The reporting period, with numeric month (1–12) and year fields.
Name
tariff_metrics
Type
array
Description
One entry per active tariff. Each entry contains tariff_id, country_code, number_type, a charges object, and a rates object.
Name
tariff_metrics[].charges
Type
object
Description
nrc (with rate_per_number, numbers_assigned_this_month, total_amount) and mrc (with rate_per_number, total_active_numbers, total_amount).
Name
tariff_metrics[].rates
Type
object
Description
Per-unit usage rates: voice_outbound_rate, voice_inbound_rate, sms_outbound_rate, sms_inbound_rate, and the currency.
Name
usage_summary
Type
object
Description
Current-month usage totals: voice (with outbound_calls, inbound_calls) and sms (with outbound_messages, inbound_messages).

Request

GET

/customers/acme/analytics/tariff-metrics

curl https://api.xnumbers.io/api/customers/acme/analytics/tariff-metrics \
  -H "Authorization: Bearer xn_your_api_key"

Response

{
  "period": {
    "month": 6,
    "year": 2026
  },
  "tariff_metrics": [
    {
      "tariff_id": "9f1c2b34-5d6e-4f70-8a91-b2c3d4e5f607",
      "country_code": "US",
      "number_type": "mobile",
      "charges": {
        "nrc": {
          "rate_per_number": 1.5,
          "numbers_assigned_this_month": 4,
          "total_amount": 6
        },
        "mrc": {
          "rate_per_number": 0.8,
          "total_active_numbers": 120,
          "total_amount": 96
        }
      },
      "rates": {
        "voice_outbound_rate": 0.012,
        "voice_inbound_rate": 0.008,
        "sms_outbound_rate": 0.0075,
        "sms_inbound_rate": 0.005,
        "currency": "USD"
      }
    }
  ],
  "usage_summary": {
    "voice": {
      "outbound_calls": 1320,
      "inbound_calls": 845
    },
    "sms": {
      "outbound_messages": 2210,
      "inbound_messages": 1675
    }
  }
}

GET/customers/{customer_slug}/analytics/asr-asd-metrics

Get ASR and ACD metrics

This endpoint returns a daily series of Answer Seizure Ratio (ASR) and Average Session Duration metrics for your voice calls over the last 7 days, filtered by call direction. Days with no calls are included with zero values.

Optional attributes

Name
direction
Type
string
Description
Call direction to analyze: "inbound" or "outbound". Defaults to "outbound".

Response properties

Name
date
Type
string
Description
The day this data point covers, formatted as YYYY-MM-DD.
Name
asr_percentage
Type
number
Description
Answer Seizure Ratio: percentage of calls answered (completed) out of all calls that day, rounded to 2 decimal places.
Name
asd_seconds
Type
number
Description
Average session duration in seconds across completed calls that day, rounded to 2 decimal places.

Request

GET

/customers/acme/analytics/asr-asd-metrics

curl -G https://api.xnumbers.io/api/customers/acme/analytics/asr-asd-metrics \
  -H "Authorization: Bearer xn_your_api_key" \
  -d direction=outbound

Response

[
  {
    "date": "2026-06-05",
    "asr_percentage": 64.29,
    "asd_seconds": 187.5
  },
  {
    "date": "2026-06-06",
    "asr_percentage": 0,
    "asd_seconds": 0
  },
  {
    "date": "2026-06-07",
    "asr_percentage": 71.43,
    "asd_seconds": 203.18
  }
]