Reference

Usage & limits

View as Markdown

Check your usage

GET /api/v1/usage returns activity analytics for your account over a selected window — headline metrics with per-day spark series and deltas, a daily activity series, voice-call duration stats, your most active numbers, and fixed-window breakdown totals. Choose the window with days (7, 30, or 90; defaults to 30).

$curl "https://api.getdial.ai/v1/usage?days=30" \
>  -H "Authorization: Bearer sk_live_..."
1{
2  "periodDays": 30,
3  "stats": {
4    "messages": { "value": 1494, "deltaPct": 17.4, "spark": [71, 53, 60] },
5    "calls":    { "value": 595,  "deltaPct": 20.4, "spark": [25, 18, 22] },
6    "minutes":  { "value": 1803, "deltaPct": null, "spark": [62, 40, 55] }
7  },
8  "series": [
9    { "date": "2026-05-05", "messages": 71, "calls": 25 }
10  ],
11  "callDuration": {
12    "sampleSize": 547,
13    "medianSec": 157,
14    "p95Sec": 516,
15    "longestSec": 980,
16    "histogram": [
17      { "label": "2–5m", "count": 265, "pct": 0.48 }
18    ]
19  },
20  "topNumbers": [
21    { "number": "+14155550142", "nickname": "Support line", "createdAt": "2026-04-20T10:00:00.000Z", "count": 1147 }
22  ],
23  "breakdown": {
24    "messages": { "d7": 359, "d30": 1494, "all": 3804 },
25    "calls":    { "d7": 128, "d30": 595,  "all": 1506 },
26    "minutes":  { "d7": 359, "d30": 1803, "all": 4452 }
27  },
28  "totals": { "messages": 3804, "calls": 1506, "numbers": 2 },
29  "currentPeriod": {
30    "start": "2026-05-20T10:00:00.000Z",
31    "end": "2026-06-20T10:00:00.000Z",
32    "daysTotal": 31,
33    "daysElapsed": 14,
34    "daysLeft": 17,
35    "all": {
36      "voice": {
37        "outbound": { "domestic": { "calls": 141, "minutes": 416 }, "intl": { "calls": 30, "minutes": 94 } },
38        "inbound":  { "domestic": { "calls": 143, "minutes": 423 }, "intl": { "calls": 30, "minutes": 77 } }
39      },
40      "messages": {
41        "outbound": { "domestic": { "count": 373 }, "intl": { "count": 60 } },
42        "inbound":  { "domestic": { "count": 384 }, "intl": { "count": 60 } }
43      }
44    },
45    "numbers": [
46      { "id": "num_abc", "number": "+14155550142", "nickname": "Support line", "createdAt": "2026-04-20T10:00:00.000Z", "breakdown": { "voice": { "outbound": { "domestic": { "calls": 0, "minutes": 0 }, "intl": { "calls": 0, "minutes": 0 } }, "inbound": { "domestic": { "calls": 0, "minutes": 0 }, "intl": { "calls": 0, "minutes": 0 } } }, "messages": { "outbound": { "domestic": { "count": 0 }, "intl": { "count": 0 } }, "inbound": { "domestic": { "count": 0 }, "intl": { "count": 0 } } } } }
47    ]
48  }
49}

deltaPct is null when the previous equal window had no activity (for example, an account younger than the selected window) — there’s no baseline to compare against.

currentPeriod is independent of the days window: it’s a monthly cycle anchored to your account’s creation date (a stand-in until billing and pricing are defined). Each number’s usage — plus an all aggregate — is split by direction (outbound/inbound) and geography (domestic/international, by country calling code relative to the Dial number).

Limits to know

  • Event waits — POST /api/v1/events/wait accepts a timeout of 1–60 seconds. To wait longer, loop the request or keep a live stream open.
  • History lists — GET /api/v1/messages and GET /api/v1/calls return up to the 100 most recent records, newest first. Use the since and direction filters on messages to narrow results.
  • Phone number format — to and from numbers must be E.164 (e.g. +14155550123).

Treat a wait 408 as “try again,” not an error. Reads are safe to retry, but writes aren’t idempotent — retrying a failed POST can send a duplicate message or place a duplicate call, so confirm before re-sending.