> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getdial.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getdial.ai/_mcp/server.

# Usage & limits

> Check account usage and understand request limits.

## 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`).

```bash
curl "https://api.getdial.ai/v1/usage?days=30" \
  -H "Authorization: Bearer sk_live_..."
```

```json
{
  "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](/documentation/reference/errors#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](#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](/documentation/platform/stream-account-events) 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](/documentation/reference/errors#retries-and-idempotency) — 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](/documentation/reference/support) 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.