<p class="crumbs"><a href="/docs/">Docs</a></p>

# Billing

You pay only on success; `meta.billing` and the `X-Charged` header say whether a call was charged. Prices: [Pricing](/pricing/).

## When you are charged

- Data returned: the listed price
- Empty search results: charged (still an answer)
- Empty trending list: free, treated as a platform error; retry
- No data from other endpoints, not found: free
- Bad parameters, platform errors, timeouts: free
- Each page of a list is billed on its own

## Per-item pricing

A few endpoints (`x.posts.quotes.list`, `x.users.mentions.list`, `x.posts.thread.list`, `x.users.search`) charge per item returned: unit price × items, never below the floor or above the cap of a call, shown as "$0.0003 per item ($0.0003–0.006 a call)". The cap is held when the call starts; once the result is in, the actual amount is charged and the rest returned at once. In `meta.billing`, `unit` is `item`, `items` the count and `amount` what was charged. X-Max-Price compares against the cap.

## X-Max-Price

Say the most you will pay for this call; above it, nothing runs and nothing is charged:

```http
X-Max-Price: 0.01
```

## Idempotency-Key

To retry safely, send the same `Idempotency-Key`. Within 24 hours the same key, Idempotency-Key and request count once; the repeat returns the first answer (`Idempotent-Replayed: true`). Reusing it for a different request answers 409.

```http
Idempotency-Key: 3b8c4d2e-…
```

## Spend caps

Set a cap per key in the [console](/console/keys/); past it, that key gets `key_spend_cap_reached` while other keys keep working.

## Insufficient balance

A 402 `insufficient_balance` carries `top_up_url`. Scripts and agents should stop, not loop.

---

HTML version: https://feedmcp.com/docs/billing/
