Skip to navigation
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_..."
{
  "periodDays": 30,
  "stats": {
    "messages": { "value": 1494, "deltaPct": 17.4, "spark": [71, 53, 60] },
    "calls":    { "value": 595,  "deltaPct": 20.4, "spark": [25, 18, 22] },
    "minutes":  { "value": 1803, "deltaPct": null, "spark": [62, 40, 55] }
  },
  "series": [
    { "date": "2026-05-05", "messages": 71, "calls": 25 }
  ],
  "callDuration": {
    "sampleSize": 547,
    "medianSec": 157,
    "p95Sec": 516,
    "longestSec": 980,
    "histogram": [
      { "label": "2–5m", "count": 265, "pct": 0.48 }
    ]
  },
  "topNumbers": [
    { "number": "+14155550142", "nickname": "Support line", "createdAt": "2026-04-20T10:00:00.000Z", "count": 1147 }
  ],
  "breakdown": {
    "messages": { "d7": 359, "d30": 1494, "all": 3804 },
    "calls":    { "d7": 128, "d30": 595,  "all": 1506 },
    "minutes":  { "d7": 359, "d30": 1803, "all": 4452 }
  },
  "totals": { "messages": 3804, "calls": 1506, "numbers": 2 },
  "currentPeriod": {
    "start": "2026-05-20T10:00:00.000Z",
    "end": "2026-06-20T10:00:00.000Z",
    "daysTotal": 31,
    "daysElapsed": 14,
    "daysLeft": 17,
    "all": {
      "voice": {
        "outbound": { "domestic": { "calls": 141, "minutes": 416 }, "intl": { "calls": 30, "minutes": 94 } },
        "inbound":  { "domestic": { "calls": 143, "minutes": 423 }, "intl": { "calls": 30, "minutes": 77 } }
      },
      "messages": {
        "outbound": { "domestic": { "count": 373 }, "intl": { "count": 60 } },
        "inbound":  { "domestic": { "count": 384 }, "intl": { "count": 60 } }
      }
    },
    "numbers": [
      { "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 } } } } }
    ]
  }
}

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.
  • WhatsApp sending — WhatsApp numbers are spaced between messages and capped on daily volume, on messages to one recipient, and on unanswered messages to the same person. See WhatsApp sending limits.
  • Number lookups — GET /api/v1/lookup is capped per account, as a short burst and again over a rolling hour. See Number lookup 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.

WhatsApp sending limits

WhatsApp watches how a number behaves and suspends numbers that act like software rather than a person. Dial paces and caps WhatsApp sends to keep your numbers in good standing. These limits apply to WhatsApp only — SMS, iMessage, and voice on the same number are unaffected, and so are reactions and typing indicators.

Every limit below is per WhatsApp number: each number you hold gets its own allowance, and a second number doesn’t inherit the first one’s usage.

Minimum spacing between messages

Consecutive messages from one number are spaced by a fixed minimum gap of at least a second. A send that arrives inside that gap is rejected with 429 (rate_limited) and a Retry-After header saying how many seconds to wait — the request is never held open while the server waits on your behalf.

Read Retry-After and come back when it says. It’s the only limit here that tells you exactly when to retry, because it’s the only one that clears on a timer rather than on something changing.

Daily and per-recipient volume

Each number has a daily cap on outbound WhatsApp messages, and a lower per-recipient cap on messages to any one person, both measured over a rolling 24 hours. Past either, sends are rejected with 429 (rate_limited). Because the window rolls, the allowance returns gradually as older messages age out rather than all at once at midnight.

Replies you haven’t received yet

Unanswered messages — 3 in a row per conversation. After three consecutive messages to one recipient with no reply from them, further sends to that recipient are rejected with 429 (rate_limited). The limit lifts the moment they reply.

It’s per conversation, not per number: other recipients are unaffected, so a number sending one-way notifications to many people keeps working. Treat this 429 as “this recipient hasn’t engaged yet,” not as a transient failure to retry — an opening message that invites a reply is what keeps a conversation inside it.

Exact values aren’t published

They’re tuned as WhatsApp’s own enforcement changes, and a number quoted here would be wrong the moment it moved. Build against the 429 rather than against an assumed ceiling.

One thing worth planning for even so: WhatsApp is hardest on newly registered numbers, and sending hard on day one is the fastest way to lose one. Dial softens the start for you: a number bought with WhatsApp arrives already warmed, and a number you connect yourself is warmed up (warming_up, about 6 hours) before it becomes ready. Even so, treat a new number’s first weeks as a ramp regardless of what the limits currently allow — and if you’re planning a high-volume WhatsApp workload, talk to us with your expected daily volume first.

Number lookup limits

Looking a number up is capped per account, as a short burst allowance and again over a rolling hour. Past either, the request is rejected with 429 (rate_limited) and a Retry-After header saying how long to wait.

Unlike the sending limits above, this one is per account, not per number — it bounds how fast an account can ask, whichever of its numbers answers.

Two things keep normal use well clear of it:

  • Repeated lookups of the same number don’t count. A verdict is cached briefly and served from there, so a retry, or two parts of your code asking about the same person, cost nothing.
  • Picking a channel once per conversation is far below the cap. The cap exists to stop a runaway loop, not to ration ordinary use.

Exact values aren’t published, for the same reason as the sending limits: they’re tuned as upstream enforcement changes. Build against the 429 and its Retry-After rather than against an assumed ceiling.