Line Usage and Capacity

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:

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 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 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 for the response schema.