> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ninjachat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cost estimation

> Price a chat request before you send it — the same pricing engine and token estimator that bill real traffic, with no key and no charge.

`POST /api/v1/estimate` estimates a chat request's cost. It is free and requires no API key. Use `estimate.create` in either SDK.

```bash cURL theme={null}
curl https://www.ninjachat.ai/api/v1/estimate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [{"role": "user", "content": "Summarize the attached incident report in five bullets."}],
    "max_tokens": 1024,
    "count": 1000,
    "models": ["gemini-3.7-flash", "claude-sonnet-5"]
  }'
```

## Parameters

| Parameter    | Type    | Default  | Description                                                                                                                                                         |
| ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`      | string  | required | A chat model ID from [`GET /models`](/models).                                                                                                                      |
| `messages`   | array   | —        | Up to 10 `system`, `user`, or `assistant` messages (content ≤ 8,000 chars each) used for the prompt-token estimate. Omit it to price a 5,000-token reference input. |
| `max_tokens` | integer | —        | Output bound for the maximum estimate (1–16,384). Also caps the typical completion.                                                                                 |
| `count`      | integer | `1`      | Multiply the estimate by this many requests (1–10,000).                                                                                                             |
| `models`     | array   | —        | Up to 10 additional model IDs to price the same payload against.                                                                                                    |

## Response

```json theme={null}
{
  "model": "gpt-5.4",
  "model_name": "GPT-5.4",
  "provider": "openai",
  "tier": "premium",
  "pricing_version": "2026-09-01.provider-rails.1",
  "billing": "metered",
  "rates": { "input_per_mtok": 2.5, "output_per_mtok": 15, "cached_input_per_mtok": 0.25 },
  "estimated_tokens": { "prompt": 24, "completion": 64 },
  "estimated_cents": 0.1,
  "estimated_cost": "$0.0010",
  "estimated_max_cents": 1.54,
  "estimated_max": "$0.0154",
  "for_count": 1000,
  "total_estimated_cents": 100,
  "total_estimated": "$1.00",
  "cheaper_alternatives": [
    { "id": "gemini-3-flash", "name": "Gemini 3 Flash", "estimated_cents": 0.02, "savings_percent": 80, "capabilities": ["..."] }
  ],
  "monthly_estimate": { "at_100": "$0.10", "at_1000": "$1.00", "at_10000": "$10.00", "at_100000": "$100.00" },
  "model_comparison": [
    { "model": "gemini-3.7-flash", "estimated_cents": 0.05, "total_estimated_cents": 50 },
    { "model": "claude-sonnet-5", "estimated_cents": 0.07, "total_estimated_cents": 70 }
  ],
  "note": "Billing is per token ($/MTok input + output). Requests preauthorize estimated_max and settle to actual usage; estimates here use the same engine and estimator that bill real traffic."
}
```

Two numbers matter:

* **`estimated_cents` / `estimated_cost`** — a realistic mid-point. The completion side uses a heuristic of 40% of the prompt tokens (at least 64), capped at `max_tokens` or 2,048.
* **`estimated_max_cents` / `estimated_max`** — the pre-authorization **hold** a real request with these messages and `max_tokens` would reserve. The hold is a reserve, not a ceiling: the request settles to actual usage and the unused portion is returned. Use it to size `routing.max_cost_usd` — a cap below the hold is rejected with `400 max_cost_exceeded`. See [Spend controls](/budget-routing).

`cheaper_alternatives` lists up to three catalog models that would cost less at this exact payload, sorted by savings. `model_comparison` appears only when you pass `models`. The numbers in the sample are illustrative; the endpoint returns live values.

## Limits

* 30 requests per minute per client IP (`429 rate_limit_exceeded` with `retry_after` and a `Retry-After` header).
* Unknown model IDs return `400 validation_error` with the closest matching ID in the message.

<CardGroup cols={2}>
  <Card title="Live price sheet" icon="receipt" href="/pricing">
    `GET /api/v1/pricing` for every model's metered rates.
  </Card>

  <Card title="Cap a request" icon="coins" href="/budget-routing">
    `routing.max_cost_usd` turns an estimate into a hard ceiling.
  </Card>
</CardGroup>