# Usage, limits & billing

Turnix plans are based on the TURN traffic your organization relays per billing period. This page explains how usage is counted and what happens at the limit.

## How usage is counted

- Usage is measured in **GB of relayed TURN traffic**.
- It is counted per **organization**, across all of its projects, for the current **billing period** (monthly, starting on your subscription date).
- Each plan includes a traffic allowance. Current plans and prices are on the [pricing page](https://turnix.io/#pricing).

You can see usage in the dashboard under [Billing](https://turnix.io/app/organization/billing) and [Stats](https://turnix.io/app/turn/statistics), or query it with the [Usage API](https://turnix.io/docs/api-reference/usage).

## What happens at the limit

It depends on whether your plan allows overage:

| Plan type | When usage reaches the included traffic |
|-----------|------------------------------------------|
| **Free plan** (no overage) | New credential requests fail with `429`. The limit is checked each time credentials are requested. |
| **Paid plans** (overage available) | Credentials keep working. Traffic above the allowance is billed as overage at your plan's per-GB rate. |

The `429` response looks like this:

```json
{
  "error": "Usage limit exceeded",
  "message": "You have reached your data usage limit",
  "limit": "15 GB",
  "used": "15.02 GB"
}
```

To recover, upgrade your plan in [Billing](https://turnix.io/app/organization/billing), or wait for the next billing period.

> **Tip: Handle 429 gracefully**
>
> A `429` from Turnix is not a rate limit, so retrying does not help. Log it, alert yourself, and let calls fall back to STUN-only (direct connections still work for many users) instead of failing hard.

## Rate limits

The API currently does not enforce a request rate limit. Request credentials once per connection, not in a polling loop.

## Monitoring usage from code

[`GET /usage/current`](https://turnix.io/docs/api-reference/usage#get-usage-current) returns the current plan, period and usage. A simple check you can run from a cron job:

```bash
curl -s https://turnix.io/api/v1/usage/current \
  -H "Authorization: Bearer $TURNIX_API_TOKEN"
# {"current_plan":"FREE","current_period_start":"...","current_period_end":"...",
#  "current_period_usage_gb":12.4,"is_overage_available":false,"limit_before_avarage_gb":15}
```

Alert when `current_period_usage_gb` approaches `limit_before_avarage_gb` and `is_overage_available` is `false`.