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

### Returns

- `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: 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.

    - `daily: LineUsageDailyWindow`

      - `resetsAt: string`

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

    - `hourly: LineUsageWindow`

      - `limit: number`

        Current limit with any account or line overrides.

      - `nextSlotAt: string`

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

      - `remaining: number`

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

      - `used: number`

        Number of new contacts counted in this window.

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

      - `"available"`

      - `"limited"`

      - `"paused"`

      - `"not_applicable"`

      - `"unavailable"`

    - `newContactLookbackDays: optional number`

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

  - `status: "OK"`

    - `"OK"`

### Example

```http
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"
```

#### Response

```json
{
  "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"
}
```