--- title: Line Usage and Capacity | Sendblue Docs description: Get new-contact usage, limits, and remaining capacity for each Sendblue line --- This endpoint returns the same data shown in the dashboard, including when each line is expected to have capacity again. ``` GET https://api.sendblue.com/api/v2/lines/usage ``` The response includes your account’s phone lines and any old lines you can still use during a replacement grace period. This endpoint does not accept query parameters. ## Example Request Use your account’s API credentials: Terminal window ``` curl "https://api.sendblue.com/api/v2/lines/usage" \ -H "sb-api-key-id: YOUR_API_KEY" \ -H "sb-api-secret-key: YOUR_API_SECRET" ``` You can also use an account-scoped temporary bearer token. A line-scoped token returns HTTP 403 because the response includes all of your account’s lines. ## Success Response (200) ``` { "status": "OK", "enabled": true, "lines": [ { "phone": "+15550100001", "state": "available", "sampledAt": "2026-10-06T17:00:00.000Z", "newContactLookbackDays": 30, "hourly": { "used": 8, "limit": 15, "remaining": 7, "nextSlotAt": "2026-10-06T17:06:00.000Z" }, "daily": { "used": 31, "limit": 50, "remaining": 19, "nextSlotAt": "2026-10-07T07:00:00.000Z", "resetsAt": "2026-10-07T07:00:00.000Z" }, "availableAt": null } ] } ``` Limits can differ by account and line. Use the values in the response rather than the example limits above. ## How Usage Is Counted Usage counts new contacts you message on each line, rather than contacts you add to your account. Dashboard messages and automations use the same limits. A contact is new if there has been no incoming or outgoing activity on that line within the number of days returned in `newContactLookbackDays`. Sending to a known contact does not count toward these new-contact limits. Other [sending limits](/limits/index.md) and exemptions still apply. ## Response Fields | Field | Description | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `enabled` | Whether usage reporting is enabled for your account. When `false`, `lines` is empty. | | `lines[].phone` | Sendblue phone line in E.164 format. | | `state` | Capacity state; see the table below. | | `sampledAt` | When usage was checked, as an ISO 8601 timestamp in UTC. | | `newContactLookbackDays` | Days without activity before a contact counts as new again. This field may be omitted. | | `hourly.used / limit / remaining` | New contacts used, the line’s limit, and capacity left in a rolling 60-minute window. | | `daily.used / limit / remaining` | New contacts used, the line’s limit, and capacity left since the last 3 AM ET reset. | | `hourly.nextSlotAt` | When the oldest counted contact leaves the hourly window; `null` if there are none or the time is unavailable. | | `daily.nextSlotAt` | Next daily reset when daily usage is nonzero; otherwise null. | | `daily.resetsAt` | Next daily reset at 3 AM ET (`America/New_York`), accounting for daylight saving time. | | `availableAt` | When a limited line is expected to have capacity in both windows; `null` if it is not limited or the time is unknown. | If a limit is lowered below current usage, `remaining` is zero. More than one contact may need to leave the hourly window before you can message a new contact, so use `availableAt` rather than `nextSlotAt` to decide when to retry. These times assume no further sends. A request does not reserve capacity, and other sending rules still apply. Use [Known Contacts per Line](/api-v2/line-contact-status/index.md) to check a contact’s status on a line before choosing which number to send from. ## Line States | State | Description | | ---------------- | -------------------------------------------------------------------------------------------- | | `available` | The line has capacity under its active new-contact limits. | | `limited` | The hourly or daily limit has been reached. Check `availableAt`. | | `paused` | The line’s daily new-contact limit is zero. | | `not_applicable` | These limits do not apply to the line, including inbound-only and free shared-line plans. | | `unavailable` | Sendblue could not retrieve usage or limit settings. Retry; do not treat this as zero usage. | Fields can be `null` when a limit is disabled, does not apply, or could not be checked. A disabled hourly limit returns `null` hourly fields. A paused line returns a daily limit and remaining capacity of zero, with `used: null`. If `enabled` is `true` but `lines` is empty, no phone lines were found. If usage is unavailable for one line, the response still includes the other lines. ## Error Responses | HTTP Status | Description | | ----------- | ------------------------------------------------------------------------------------------------------- | | 400 | Query parameters are not accepted. | | 401 | Invalid API credentials or temporary token. | | 403 | Missing authentication or a line-scoped temporary token requesting account-wide usage. | | 429 | API request rate limit exceeded. | | 500 | Sendblue could not retrieve your account’s usage. Retry; do not treat this as an account with no lines. | Responses use `Cache-Control: no-store`. The dashboard refreshes every 15 seconds while the page is open. If your integration polls this endpoint, handle HTTP 429 responses and slow down when rate limited. See the [API reference](/api/resources/lines/methods/get_usage/index.md) for the response schema.