> For the complete documentation index, see [llms.txt](https://docs.trezalabs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trezalabs.com/ai-gateway/usage-and-billing.md).

# Usage & Billing

The AI Control Plane meters one thing: **redaction requests**. This page covers how requests are counted, the usage-insights API behind the dashboard, and the audit log export.

### How requests are counted

* **Billable:** each `POST /api/redact/chat/completions` call routed through the proxy counts as one redaction request, recorded at request time. On metered plans (Pro, Enterprise) each request also emits a Stripe meter event with an idempotency key, so a request is never double-billed.
* **Not billed:** `POST /api/redact/run` (standalone redaction), `POST /api/proxies/test` (policy dry runs), and all dashboard/management calls.
* Usage recording is best-effort and never delays or blocks the proxy response.

What happens when you exhaust the requests included in your plan depends on the tier:

| Plan       | Included requests / period | Beyond the included amount                             |
| ---------- | -------------------------- | ------------------------------------------------------ |
| Starter    | 1,000                      | Requests are rejected with `402`, `code: "PLAN_LIMIT"` |
| Pro        | 50,000                     | Requests keep flowing; overage billed at $0.002 each   |
| Enterprise | 1,000,000                  | Requests keep flowing; per custom contract             |

The included quota resets at the start of each billing period. See [Plans & Pricing](/ai-gateway/plans-and-pricing.md) for the full tier comparison.

### Usage insights

The **Usage & insights** tab in the Control Plane dashboard shows request volume over time, per-proxy totals, and PII entities redacted by type. The same data is available from the API:

`GET /api/usage?days=30` — authenticates as the **dashboard user** (Treza session access token), not a `treza_live_...` API key. `days` ranges from 1 to 90 (default 30).

```bash
curl "https://trezalabs.com/api/usage?days=30" \
  -H "Authorization: Bearer $TREZA_SESSION_TOKEN"
```

```json
{
  "totalRequests": 1284,
  "meteredRequests": 1284,
  "totalEntitiesRedacted": 3911,
  "series": [
    { "date": "2026-06-10", "count": 412 },
    { "date": "2026-06-11", "count": 872 }
  ],
  "byProxy": { "proxy_1718039482_ab12cd34e": 1284 },
  "entitiesByType": { "EMAIL": 1450, "PHONE": 1203, "SSN": 644, "CC": 614 },
  "recent": [
    {
      "requestId": "req_lx2k9a_1f3b7c2d",
      "ts": "2026-06-11T18:21:09.412Z",
      "source": "proxy",
      "counts": { "EMAIL": 1, "SSN": 1 }
    }
  ],
  "entitlements": {
    "planId": "pro",
    "usage": { "requestsThisPeriod": 1284, "includedRequests": 50000, "overLimit": false }
  }
}
```

| Field                   | Meaning                                              |
| ----------------------- | ---------------------------------------------------- |
| `totalRequests`         | Proxied requests in the window                       |
| `meteredRequests`       | Requests that emitted a Stripe meter event           |
| `totalEntitiesRedacted` | Sum of PII entities redacted across all requests     |
| `series`                | Per-day request counts                               |
| `byProxy`               | Request counts per proxy id                          |
| `entitiesByType`        | Redacted entity counts by type (`EMAIL`, `SSN`, …)   |
| `recent`                | The 25 most recent redaction audit entries           |
| `entitlements`          | Your current plan, feature flags, and quota position |

For a per-API-key view from your application, use `GET /api/redact/log` instead — see the [Quickstart](/ai-gateway/quickstart.md#6-view-the-audit-log).

### Audit log export (Pro+)

`GET /api/usage/export?days=30` downloads the redaction audit log as CSV. Requires the **audit export** entitlement (Pro and above); other plans receive `403` with `code: "PLAN_FEATURE"`. Like `/api/usage`, it authenticates as the dashboard user, and `days` ranges from 1 to 90.

```bash
curl -OJ "https://trezalabs.com/api/usage/export?days=30" \
  -H "Authorization: Bearer $TREZA_SESSION_TOKEN"
# → treza-redaction-audit-30d-2026-06-12.csv
```

CSV columns:

| Column               | Description                                                              |
| -------------------- | ------------------------------------------------------------------------ |
| `timestamp`          | When the request was redacted (ISO 8601)                                 |
| `request_id`         | Matches the `x-treza-request-id` response header                         |
| `source`             | `proxy` (chat completions) or `run` (standalone redaction)               |
| `attestation_ref`    | Redaction environment id (see [Attestation](/ai-gateway/attestation.md)) |
| `model_version`      | Redaction model version                                                  |
| `recognizer_version` | Entity recognizer version                                                |
| `entities_redacted`  | Total entities redacted in the request                                   |
| `entity_breakdown`   | Per-type counts, e.g. `EMAIL:1;SSN:2`                                    |

Each export covers up to 5,000 of the most recent entries in the selected window. Audit entries contain entity **counts by type** only — never the original or redacted values.

### Plan-gating errors

API responses use two error codes for plan enforcement:

| Code           | Status      | Meaning                                                                 |
| -------------- | ----------- | ----------------------------------------------------------------------- |
| `PLAN_LIMIT`   | `402`       | A numeric limit was hit (included requests used up, proxy cap reached)  |
| `PLAN_FEATURE` | `402`/`403` | The feature requires a higher tier (e.g. custom policies, audit export) |

```json
{
  "error": "You've used all 1000 redaction requests included in your Starter plan. Upgrade to keep routing requests.",
  "code": "PLAN_LIMIT"
}
```

{% hint style="info" %}
Redaction proxy usage draws from your prepaid credit balance, like any other model usage. See [Plans & Pricing](/ai-gateway/plans-and-pricing.md).
{% endhint %}

### Related

* [Plans & Pricing](/ai-gateway/plans-and-pricing.md) — tiers, included volumes, and overage rates
* [Quickstart](/ai-gateway/quickstart.md) — the per-API-key redaction log
* [Attestation](/ai-gateway/attestation.md) — what `attestation_ref` proves