Call Information

List dial metrics

Changed on

Returns dials-per-second (DPS) metrics for your account's outbound dials made with the Call Control Dial command and TeXML, as time buckets with dial counts, accepted and rejected dials, average and peak DPS, and the DPS limit in force.

The result has one record per region per bucket, ordered by start_time and then region, newest first unless sort=start_time. Regions are never summed: the DPS limit is enforced per region, so a cross-region total cannot be compared with it.

Only buckets that saw dials are returned. Treat a missing bucket as zero dials.

Only complete 5-second windows are counted, and a window is counted about 15 seconds after it closes. The newest granularity=second record is therefore your live DPS, about 20 seconds old. Request the last minute or two with sort=-start_time; the first record of each region is that region's live rate (page[limit]=1 would hide every region but one). If no recent record exists, the live rate is zero.

Results are cursor paginated. Follow meta.next, or pass meta.cursors.after as page[after], until meta.next is absent. No total count is returned.

This endpoint is in development and can change before general availability.

get/dial_metrics

Request

  • Base URL: https://api.telnyx.com/v2
  • URL: https://api.telnyx.com/v2/dial_metrics
  • Auth: HTTP bearer

Query parameters

granularity'second' | 'minute' | 'hour' required

Bucket size. second returns 5-second buckets (the finest resolution) and is kept for the last 48 hours. minute and hour are kept for the last 30 days.

start_timestring date-time required

Inclusive start of the range, ISO 8601 (for example 2026-09-29T12:00:00.000Z). Buckets that start at or after this time are returned. A start_time older than the retention window of the chosen granularity is moved forward to the start of that window, and meta.start_time returns the start actually used.

end_timestring date-time required

Exclusive end of the range, ISO 8601. Must be after start_time. Buckets that start before this time are returned.

sort'-start_time' | 'start_time'

Sort order of the buckets by start_time. -start_time (default) returns the newest first, start_time the oldest first. region follows the same direction for buckets with the same start_time. To read the live rate, use granularity=second and sort=-start_time, then take the first record of each region.

page[after]string

Opaque cursor from meta.cursors.after of the previous page. Do not parse or construct it. A cursor that matches no records returns an empty page whose meta.cursors.after and meta.cursors.before both echo the given cursor.

page[limit]integer

Maximum number of buckets per page. Values outside the range are clamped to 1-10,000.

Response

Successful response with a page of dial metrics buckets.

Example response

{
  "data": [
    {
      "record_type": "dial_metric",
      "region": "us",
      "start_time": "2026-09-29T12:00:00.000Z",
      "end_time": "2026-09-29T13:00:00.000Z",
      "dials": {
        "total": 85600,
        "accepted": 85240,
        "rejected": {
          "dps_limit": 360
        }
      },
      "average_dps": 23.7778,
      "peak_dps": 104,
      "dps_limit": 100
    }
  ],
  "meta": {
    "granularity": "hour",
    "start_time": "2026-09-29T12:00:00.000Z",
    "end_time": "2026-09-29T14:00:00.000Z",
    "cursors": {
      "after": "MTc5MDY4NjgwMDpldQ",
      "before": "MTc5MDY4MzIwMDp1cw"
    },
    "next": "/v2/dial_metrics?end_time=2026-09-29T14%3A00%3A00.000Z&granularity=hour&page%5Bafter%5D=MTc5MDY4NjgwMDpldQ&page%5Blimit%5D=2&sort=-start_time&start_time=2026-09-29T12%3A00%3A00.000Z",
    "sort": "-start_time"
  }
}

Changes