Get live line usage and capacity

GET/api/v2/lines/usage

Get each line’s hourly and daily new-contact usage, limits, remaining capacity, and when capacity becomes available again. Includes your account’s phone lines and old lines still available during a replacement grace period. The hourly window is a rolling 60 minutes; daily usage resets at 3 AM ET (America/New_York). Counts apply to new contacts you message, rather than contacts you add to your account. Dashboard messages and automations use the same limits.

Requests do not reserve capacity. Recovery times assume no further sends. This endpoint accepts no query parameters. Use API credentials or an account-scoped temporary token.

ReturnsExpand Collapse

LineUsageResponse object { enabled, lines, status }

enabled: boolean

Whether usage reporting is enabled for your account. When false, lines is empty.

lines: array of LineUsageSnapshot { availableAt, daily, hourly, 4 more }

availableAt: string

When a limited line is expected to have capacity in both windows, assuming no further sends. Null if the line is not limited or the time is unknown.

formatdate-time

daily: LineUsageDailyWindow { resetsAt }

resetsAt: string

Next daily reset at 3 AM ET (America/New_York), accounting for daylight saving time.

formatdate-time

hourly: LineUsageWindow { limit, nextSlotAt, remaining, used }

limit: number

Current limit with any account or line overrides.

minimum0

nextSlotAt: string

When the oldest counted contact leaves this window. If the limit was lowered below usage, use availableAt to decide when to retry.

formatdate-time

remaining: number

New contacts you can still message in this window. Zero if current usage exceeds a lowered limit.

minimum0

used: number

Number of new contacts counted in this window.

minimum0

phone: string

The account’s Sendblue phone line in E.164 format.

sampledAt: string

state: "available" or "limited" or "paused" or 2 more

Current capacity status. Paused means the daily limit is zero; not_applicable means these limits do not apply; unavailable means usage or settings could not be checked.

One of the following:

"available"

"limited"

"paused"

"not_applicable"

"unavailable"

newContactLookbackDays: optional number

Days without activity before a contact counts as new again. This field may be omitted.

minimum0

exclusiveMinimum

status: "OK"

Get live line usage and capacity

curl https://api.sendblue.co/api/v2/lines/usage \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET"

{
  "enabled": true,
  "lines": [
    {
      "availableAt": null,
      "daily": {
        "limit": 50,
        "nextSlotAt": "2026-10-07T07:00:00.000Z",
        "remaining": 19,
        "used": 31,
        "resetsAt": "2026-10-07T07:00:00.000Z"
      },
      "hourly": {
        "limit": 15,
        "nextSlotAt": "2026-10-06T17:06:00.000Z",
        "remaining": 7,
        "used": 8
      },
      "phone": "+15550100001",
      "sampledAt": "2026-10-06T17:00:00.000Z",
      "state": "available",
      "newContactLookbackDays": 30
    }
  ],
  "status": "OK"
}

Returns Examples

{
  "enabled": true,
  "lines": [
    {
      "availableAt": null,
      "daily": {
        "limit": 50,
        "nextSlotAt": "2026-10-07T07:00:00.000Z",
        "remaining": 19,
        "used": 31,
        "resetsAt": "2026-10-07T07:00:00.000Z"
      },
      "hourly": {
        "limit": 15,
        "nextSlotAt": "2026-10-06T17:06:00.000Z",
        "remaining": 7,
        "used": 8
      },
      "phone": "+15550100001",
      "sampledAt": "2026-10-06T17:00:00.000Z",
      "state": "available",
      "newContactLookbackDays": 30
    }
  ],
  "status": "OK"
}