---
title: Key and limits
description: GET /v1/key (key, 30-day usage, balance and request limit), GET /v1/generation (request cost by id), rate-limit headers and the 429 response for LLM chat.
icon: Gauge
---

`GET /v1/key` shows which key you're using, how much it spent over the last 30 days, how many credits the account has available and the key's request limit. The cost of an individual chat request is returned by `GET /v1/generation` for the response `id`.

## Key information [#key]

<Method name="GET" path="/v1/key" />

```bash
curl https://api.clipia.ai/v1/key \
  -H "Authorization: Bearer $CLIPIA_KEY"
```

**Response `200`**

```json
{
  "data": {
    "label": "prod key (····a1b2)",
    "limit": null,
    "usage": 1240.5,
    "limit_remaining": 8320,
    "is_free_tier": false,
    "rate_limit": { "requests": 120, "interval": "1m" }
  }
}
```

<TypeTable
  type={{
    label: { type: 'string', description: 'Key name and its last four characters. For an OAuth connection — "Connected session".' },
    limit: { type: 'null', description: 'The key has no separate spending limit; always null.' },
    usage: { type: 'number', description: 'Credits this key spent over the last 30 days, net of refunds.' },
    limit_remaining: { type: 'number', description: 'Credits currently available on the account. The balance is shared by all keys.' },
    is_free_tier: { type: 'boolean', description: 'Always false.' },
    'rate_limit.requests': { type: 'integer', description: 'The key\'s request limit per minute.' },
    'rate_limit.interval': { type: 'string', description: 'The limit window, always "1m".' },
  }}
/>

The same balance, split into subscription and purchased credits, is returned by [`GET /v1/account`](/en/docs/api-reference/account).

## Request cost [#cost]

The chat response's `usage` holds token counts only (in a stream, in the last chunk when `stream_options: { "include_usage": true }` is set — see [Chat Completions](/en/docs/llm-gateway/chat-completions)). The cost of a completed request in credits is returned by `GET /v1/generation`: pass the response identifier `chatcmpl-…` (for `POST /v1/completions`, `cmpl-…`) or a generation `request_id` as `id`.

<Method name="GET" path="/v1/generation" />

```bash
curl "https://api.clipia.ai/v1/generation?id=chatcmpl-3f9a1c7e2b41" \
  -H "Authorization: Bearer $CLIPIA_KEY"
```

**Response `200`**

```json
{
  "data": {
    "id": "chatcmpl-3f9a1c7e2b41",
    "total_cost": 0.046,
    "tokens_prompt": 28,
    "tokens_completion": 64,
    "native_tokens_prompt": 28,
    "native_tokens_completion": 64,
    "finish_reason": null,
    "model": "claude-opus-5-5",
    "provider": "Clipia",
    "streamed": null,
    "created_at": "2026-11-04T12:00:00.000Z"
  }
}
```

<TypeTable
  type={{
    id: { type: 'string', description: 'The identifier you passed in the request.' },
    total_cost: { type: 'number', description: 'Credits charged, fractional.' },
    tokens_prompt: { type: 'integer | null', description: 'Input tokens.' },
    tokens_completion: { type: 'integer | null', description: 'Output tokens.' },
    native_tokens_prompt: { type: 'integer | null', description: 'Same as tokens_prompt.' },
    native_tokens_completion: { type: 'integer | null', description: 'Same as tokens_completion.' },
    finish_reason: { type: 'null', description: 'Not stored in the log; always null.' },
    model: { type: 'string | null', description: 'Identifier of the model that answered.' },
    provider: { type: 'string', description: 'Always "Clipia".' },
    streamed: { type: 'null', description: 'Not stored in the log; always null.' },
    created_at: { type: 'string', description: 'Request time, ISO 8601.' },
  }}
/>

The lookup covers only your own account's requests: someone else's or an unknown `id` returns `404 not_found`. The key's total 30-day spend is in `GET /v1/key`, and the request log is on the **Logs** tab of the [Developer Console](/en/developer).

## Limits [#limits]

LLM chat is subject to the same limits as the rest of the API:

- **120 requests per minute per key** and 600 across all of the account's keys; 60 requests per minute for an OAuth connection;
- a **concurrency limit**, if one is set for the key or the account;
- a **tokens-per-minute limit**, if the Clipia team has set one, and a **credit budget**, if the key owner has set one; none by default.

See [Rate limits](/en/docs/api-reference/rate-limits) for details.

### Response headers

<TypeTable
  type={{
    'RateLimit-Limit': { type: 'integer', description: 'The key\'s request limit per minute.' },
    'RateLimit-Remaining': { type: 'integer', description: 'Requests the key has left in the current minute.' },
    'RateLimit-Reset': { type: 'integer', description: 'When the window resets, as Unix time in seconds.' },
    'x-ratelimit-remaining-requests': { type: 'integer', description: 'Same as RateLimit-Remaining, in OpenAI format.' },
    'x-ratelimit-remaining-tokens': { type: 'integer', description: 'Tokens left in the current minute. Only when a token limit is set.' },
    'Retry-After': { type: 'integer', description: 'Sent with a 429: how many seconds to wait before retrying.' },
  }}
/>

Streaming responses (`stream: true`) do not carry these headers: the server sends only the SSE headers. Read the limits from a regular request instead, such as `GET /v1/key`.

### 429 response

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json
```

```json
{
  "error": {
    "message": "API rate limit exceeded. Slow down and retry after the reset window.",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}
```

<Callout type="info" title="Respect Retry-After">
On a `429`, wait the number of seconds given in `Retry-After` before retrying — that's more reliable than a fixed delay.
</Callout>
