> ## 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

> Know the cost before you run anything. Always free, no key required.

Chat bills per token — `/estimate` runs the exact same pricing engine and token
estimator that bills real traffic, so it can never disagree with what you're
actually charged.

```json POST /api/v1/estimate theme={null}
{
  "model": "claude-sonnet-4.6",
  "messages": [{"role": "user", "content": "Summarize this document..."}],
  "count": 1000
}
```

```json Response theme={null}
{
  "model": "claude-sonnet-4.6",
  "model_name": "Claude Sonnet 4.6",
  "provider": "Anthropic",
  "billing": "metered",
  "rates": {
    "input_per_mtok": 3.0,
    "output_per_mtok": 15.0,
    "cached_input_per_mtok": 0.3
  },
  "estimated_tokens": { "prompt": 62, "completion": 64 },
  "estimated_cents": 0.11,
  "estimated_cost": "$0.0011",
  "estimated_max_cents": 3.15,
  "estimated_max": "$0.0315",
  "for_count": 1000,
  "total_estimated_cents": 110.0,
  "total_estimated": "$1.1000",
  "cheaper_alternatives": [
    {"id": "gpt-5", "name": "GPT-5", "estimated_cents": 0.05, "savings_percent": 55, "capabilities": ["text", "code"]}
  ],
  "monthly_estimate": {"at_100": "$0.11", "at_1000": "$1.10", "at_10000": "$11.00", "at_100000": "$110.00"},
  "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."
}
```

`estimated_cents`/`estimated_cost` is a realistic mid-point for this exact payload — pass `messages` for a real token count, or omit them and it falls back to a 5K-token reference input. `estimated_max`/`estimated_max_cents` is the *ceiling*: what a real request with these messages and `max_tokens` would preauthorize against your balance before settling down to actual usage. Nothing is ever charged more than what you actually used — `estimated_max` exists so you can budget for the worst case, not because it's what you'll typically pay.

No API key needed — and the endpoint doesn't read one either. `rates` are the live `$`/MTok numbers this model bills at; pass `Authorization` if you like for consistency with your other requests, but it has no effect here.

<Accordion title="Full response shape">
  Also included: `pricing_version`, `tier`, `for_count`, `total_estimated_cents`/`total_estimated` (estimated\_cents × count), and — when you pass `models` — a `model_comparison` array. Every cents field is a float; round for display, don't truncate.
</Accordion>

## Parameters

| Parameter    | Default  | Description                                                                                                                            |
| ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `model`      | required | Any concrete model ID (not `auto*`) — `ensemble`/`ensemble-quality` are supported and sum their member calls.                          |
| `messages`   | —        | Improves the token estimate — the real byte-aware estimator this API bills with. Omit and it falls back to a 5K-token reference input. |
| `max_tokens` | `2048`   | Bounds `estimated_max` — the output ceiling a real request would hold against your balance.                                            |
| `count`      | `1`      | Requests to price (1–10,000).                                                                                                          |
| `models`     | —        | Also return a side-by-side `model_comparison` across these IDs.                                                                        |

## Compare prices across models

```json theme={null}
{
  "model": "claude-sonnet-4.6",
  "messages": [{"role": "user", "content": "Summarize this document..."}],
  "count": 50000,
  "models": ["gpt-5-mini", "deepseek-v3", "gpt-5", "claude-sonnet-4.6", "claude-opus-4.6"]
}
```

```json theme={null}
{
  "model_comparison": [
    {"model": "gpt-5-mini",        "estimated_cents": 0.03, "total_estimated_cents": 1500},
    {"model": "deepseek-v3",       "estimated_cents": 0.04, "total_estimated_cents": 2000},
    {"model": "gpt-5",             "estimated_cents": 0.05, "total_estimated_cents": 2500},
    {"model": "claude-sonnet-4.6", "estimated_cents": 0.11, "total_estimated_cents": 5500},
    {"model": "claude-opus-4.6",   "estimated_cents": 0.18, "total_estimated_cents": 9000}
  ]
}
```

Numbers above are illustrative for this example payload — real figures scale with your actual token counts. Always read live numbers from the endpoint.

## Guard a batch before running it

```python theme={null}
import requests

def estimated_max_cents(model: str, messages: list, max_tokens: int = 2048) -> float:
    r = requests.post("https://www.ninjachat.ai/api/v1/estimate",
        json={"model": model, "messages": messages, "max_tokens": max_tokens})
    return r.json()["estimated_max_cents"]

cost = estimated_max_cents("claude-sonnet-4.6", my_messages) * 10_000  # 10k-item batch
if cost > 5000:  # $50 budget
    print(f"Too expensive (worst case ${cost/100:.2f}) — try gpt-5 or deepseek-v3")
else:
    pass  # run the batch
```

<Tip>
  Agents get the same guarantee over MCP — `estimate_cost` is one of the free [MCP tools](/mcp/tools).
</Tip>