# Usage

Read your organization's plan and relayed traffic. Usage is counted per organization across all projects. See [Usage, limits & billing](https://turnix.io/docs/concepts/usage-limits) for how limits work.

## `GET /usage/current`

Returns the current plan and the traffic in the current billing period.

```bash
curl https://turnix.io/api/v1/usage/current \
  -H "Authorization: Bearer $TURNIX_API_TOKEN"
```

`200 OK`

```json
{
  "current_plan": "STARTUP",
  "current_period_start": "2026-10-18T20:32:04.000Z",
  "current_period_end": "2026-11-18T20:32:04.000Z",
  "current_period_usage_gb": 78.79,
  "is_overage_available": true,
  "limit_before_avarage_gb": 150
}
```

| Field | Type | Description |
|-------|------|-------------|
| `current_plan` | string | Plan name |
| `current_period_start`, `current_period_end` | string | Current billing period (ISO 8601, UTC) |
| `current_period_usage_gb` | number | Relayed traffic in this period, in GB |
| `is_overage_available` | boolean | `true`: traffic above the allowance is billed as overage. `false`: credential requests return `429` once the allowance is used up. |
| `limit_before_avarage_gb` | number | Traffic included in the plan, in GB. (The field name is spelled `avarage` in the API.) |

Errors: `401 {"error":"You are not on any subscription","code":401}` if the organization has no active plan.

## `GET /usage/list_periods`

Returns all billing periods of your organization, oldest first, with their traffic.

```bash
curl https://turnix.io/api/v1/usage/list_periods \
  -H "Authorization: Bearer $TURNIX_API_TOKEN"
```

`200 OK`

```json
{
  "subscription_periods": [
    {
      "subscription": { "name": "FREE" },
      "current_period_start": "2026-08-18T20:32:04.000Z",
      "current_period_end": "2026-09-18T20:32:04.000Z",
      "usage": 4.22
    },
    {
      "subscription": { "name": "STARTUP" },
      "current_period_start": "2026-09-18T20:32:04.000Z",
      "current_period_end": "2026-10-18T20:32:04.000Z",
      "usage": 55.76
    }
  ]
}
```

| Field | Description |
|-------|-------------|
| `subscription.name` | Plan during that period |
| `current_period_start`, `current_period_end` | Period boundaries (ISO 8601, UTC) |
| `usage` | Relayed traffic in that period, in GB |