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. We will look at how to retrieve usage data and detailed reporting metrics.

The usage model

The usage model contains aggregated statistics about communication activity for virtual numbers, including inbound/outbound call and SMS counts over specified time periods.

Properties

Name
number_id
Type
string
Description
The virtual number ID this usage data is associated with.
Name
period_start
Type
timestamp
Description
Start of the usage period.
Name
period_end
Type
timestamp
Description
End of the usage period.
Name
inbound_calls
Type
number
Description
Number of inbound calls received.
Name
outbound_calls
Type
number
Description
Number of outbound calls made.
Name
inbound_sms
Type
number
Description
Number of inbound SMS messages received.
Name
outbound_sms
Type
number
Description
Number of outbound SMS messages sent.
Name
daily_breakdown
Type
array
Description
Day-by-day breakdown of usage statistics.

GET/numbers/:id/usage

Get usage data

This endpoint allows you to fetch aggregated usage data for a specific virtual number, including inbound/outbound call and SMS counts over a specified time period.

Optional attributes

Name
start_date
Type
string
Description
Start date for usage period (ISO 8601 format). Defaults to 30 days ago.
Name
end_date
Type
string
Description
End date for usage period (ISO 8601 format). Defaults to current date.
Name
granularity
Type
string
Description
Data granularity: "day", "week", "month". Defaults to "day".
Name
timezone
Type
string
Description
Timezone for date calculations (e.g., "America/New_York").
Name
include_breakdown
Type
boolean
Description
Whether to include daily/weekly breakdown data. Defaults to true.

Request

GET

/numbers/num_WAz8eIbvDR60rouK/usage

curl -G https://api.xnumbers.io/v1/numbers/num_WAz8eIbvDR60rouK/usage \
  -H "Authorization: Bearer {token}" \
  -d start_date=2024-01-01 \
  -d end_date=2024-01-31 \
  -d granularity=day \
  -d include_breakdown=true

Response

{
  "number_id": "num_WAz8eIbvDR60rouK",
  "period_start": "2024-01-01T00:00:00Z",
  "period_end": "2024-01-31T23:59:59Z",
  "inbound_calls": 52,
  "outbound_calls": 35,
  "inbound_sms": 156,
  "outbound_sms": 78,
  "daily_breakdown": [
    {
      "date": "2024-01-01",
      "inbound_calls": 2,
      "outbound_calls": 1,
      "inbound_sms": 5,
      "outbound_sms": 3
    }
  ]
}

GET/analytics/account

Get account-wide analytics

This endpoint provides aggregated usage analytics across all virtual numbers in your account. Useful for account-level reporting and usage summaries.

Optional attributes

Name
start_date
Type
string
Description
Start date for analytics period (ISO 8601 format).
Name
end_date
Type
string
Description
End date for analytics period (ISO 8601 format).
Name
group_by
Type
string
Description
Group results by: "number", "country", "type". Defaults to "number".
Name
limit
Type
integer
Description
Limit the number of grouped results returned.

Request

GET

/analytics/account

curl -G https://api.xnumbers.io/v1/analytics/account \
  -H "Authorization: Bearer {token}" \
  -d start_date=2024-01-01 \
  -d end_date=2024-01-31 \
  -d group_by=country

Response

{
  "period_start": "2024-01-01T00:00:00Z",
  "period_end": "2024-01-31T23:59:59Z",
  "summary": {
    "total_numbers": 15,
    "inbound_calls": 789,
    "outbound_calls": 458,
    "inbound_sms": 2134,
    "outbound_sms": 1322
  },
  "breakdown": [
    {
      "group": "US",
      "numbers_count": 12,
      "inbound_calls": 689,
      "outbound_calls": 400,
      "inbound_sms": 1856,
      "outbound_sms": 1131
    },
    {
      "group": "CA",
      "numbers_count": 3,
      "inbound_calls": 100,
      "outbound_calls": 58,
      "inbound_sms": 278,
      "outbound_sms": 191
    }
  ]
}