---
title: "List dial metrics"
method: GET
path: "/dial_metrics"
tags: ["Call Information"]
---

# List dial metrics

`GET /dial_metrics`

## Request

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

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.

## Query parameters

- `granularity` 'second' | 'minute' | 'hour', required
- `start_time` string, date-time, required
- `end_time` string, date-time, required
- `sort` '-start_time' | 'start_time'
- `page[after]` string
- `page[limit]` integer

## Response `200`

Successful response with a page of dial metrics buckets.

- ListDialMetricsResponse
  - `data` DialMetric[]
    - `record_type` 'dial_metric'
    - `region` string: Region where the dials were handled. Current values are `us`, `eu`, `australia`, `middle_east`, `canada` and `india`. New values can be added, so clients must tolerate values not listed here. Buckets of different regions are separate records.
    - `start_time` string, date-time: Start of the bucket (inclusive), UTC.
    - `end_time` string, date-time: End of the bucket (exclusive), UTC. Five seconds, one minute or one hour after `start_time`, depending on `granularity`.
    - `dials` object: Dial attempt counts in the bucket.
      - `total` integer: All dial attempts, rejected ones included: accepted plus every rejected count.
      - `accepted` integer: Dial attempts that were not rejected by a limit.
      - `rejected` object: Dial attempts rejected by a limit.
        - `dps_limit` integer: Rejected by the dials-per-second limit.
        - `hourly_limit` integer: Rejected by an hourly limit.
        - `daily_limit` integer: Rejected by a daily limit.
    - `average_dps` number: `dials.total` divided by the bucket duration in seconds, rounded to 4 decimal places. Counts every dial attempt, rejected ones included.
    - `peak_dps` number: Dials per second, rounded to 4 decimal places, in the busiest 5-second window of the bucket, summed across all call-processing nodes of the region. Counts every dial attempt, rejected ones included, so `peak_dps` above `dps_limit` is expected when dials were rejected. For `granularity=second` it equals `average_dps`.
    - `dps_limit` integer, nullable: DPS limit in force during the busiest 5-second window, so it compares directly with `peak_dps`. `null` means unlimited. Enforcement near the limit is approximate; `dials.rejected.dps_limit` is the authoritative signal that the limit was reached.
  - `meta` DialMetricsListMeta
    - `granularity` 'second' | 'minute' | 'hour': Echo of the requested granularity.
    - `start_time` string, date-time: Start of the range actually used: the requested `start_time`, or the start of the retention window when the requested value is older.
    - `end_time` string, date-time: Echo of the requested `end_time`.
    - `cursors` object: Empty on the last page. When `page[after]` matched no records, the page is empty and `after` and `before` both echo the given cursor.
      - `after` string: Opaque cursor for the next page. Pass it as `page[after]`.
      - `before` string: Present only on an empty page for a cursor that matched nothing: echoes that cursor.
    - `next` string: Path to the next page, repeating this request's parameters. Absent on the last page.
    - `sort` '-start_time' | 'start_time': Echo of the applied sort order.

## Other responses

- `401`: Unauthorized. Authentication failed - the required authentication headers were either invalid or not included in the request.
- `404`: Resource not found. The route does not exist.
- `422`: Unprocessable entity. A required parameter is missing, a parameter has an invalid value, or the whole range ends at or before the start of the retention window of the chosen granularity.
- `429`: Too many requests. The API request rate limit was exceeded. Wait before retrying; honor `Retry-After` when present. See API rate limiting. This is the request rate limit, not the dials-per-second limit of outbound calls.
- `500`: Internal server error. An unexpected error occurred on the server. This is typically returned for unhandled exceptions or system failures.
- `default`: Unexpected error

## Changes

> 152 revisions in range; 1 not diffed.

- **2026-10-20** `ecc35f40019d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/dial_metrics/get.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/f82938f53ff4?raw)