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

  • Free accounts — an account that has never added credit and never subscribed is capped at 5 minutes per call and 2 concurrent calls, inbound and outbound combined — an outbound call over the concurrency limit is rejected with 429 (call_limit_reached), an inbound one is declined. A maxCallDurationSeconds you send explicitly above the 5-minute ceiling returns 400; one inherited from the number or account is clamped to it. Both limits lift permanently on your first top-up or subscription, and their current values are on limits in GET /api/v1/account. See Free accounts.
  • iMessage sending — each iMessage number can start up to 50 new conversations a day, and sustained volume is capped above that. See iMessage sending limits.
  • 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.

iMessage sending limits

iMessage carries send limits that SMS doesn’t, to keep lines in good standing. SMS and voice numbers are unaffected.

New conversations — 50 per number per day. A new conversation is the first message a number sends to a recipient it has never messaged before; replies within a conversation that already exists don’t count. The allowance is per iMessage number, so each number you hold gets its own and a second number doesn’t inherit the first one’s usage.

Past the cap, sends are rejected with 429 (rate_limited) until the window resets. Retrying inside the same window fails the same way — wait for the reset, or send from a different iMessage number.

Sustained volume is capped separately, above the per-number level. If you’re planning a high-volume iMessage workload, talk to us with your expected daily volume before you build against it, rather than sizing your integration against an assumed ceiling.

New contacts who haven’t replied yet

Separate from the daily caps, the iMessage network limits how many messages you can send to a recipient who has never replied to your number. Past that, sends are rejected with 429 (rate_limited); the limit lifts as soon as they reply.

This is an anti-spam protection, not a Dial quota, so there’s no way to raise it — and it’s why an opening message should invite a reply rather than start a one-way sequence. Treat this 429 as “this recipient hasn’t opted in yet,” not as a transient failure to retry.