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

# Billing

> What each call costs, and how to keep a call from costing more than you meant.

API calls draw on the same monthly credits as the rest of Spyglass. There's no
separate API plan and no per-call fee — you're charged **per row returned**.

## Rates

| Endpoint                         | Unit         | Per row  | A 100-row call          |
| -------------------------------- | ------------ | -------- | ----------------------- |
| `POST /brands/search`            | brand        | \$0.0025 | \$0.25                  |
| `GET /brands/{id}`               | brand        | \$0.0025 | always 1 row — \$0.0025 |
| `POST /brands/{id}/media`        | creative     | \$0.0010 | \$0.10                  |
| `GET /brands/{id}/insights`      | cluster      | \$0.0010 | \$0.10                  |
| `GET /brands/{id}/landing-pages` | landing page | \$0.0050 | \$0.50                  |

The `count` field in a collection response is what you were charged for. If
`count` is 12, you paid for 12 rows. Two things don't follow that rule:
`GET /brands/{id}` returns a bare brand with no `count`, because a successful
lookup is always exactly one row; and the one-row minimum below, where a `count`
of `0` still costs one row.

## Bounding a call

Every endpoint takes a cap, and the defaults are not the maximums:

`GET /brands/{id}` needs no cap — it returns one brand or `404`.

| Endpoint                     | Parameter | Default | Max                          |
| ---------------------------- | --------- | ------- | ---------------------------- |
| `/brands/search`             | `count`   | 10      | 100 (20 for `mode: "smart"`) |
| `/brands/{id}/media`         | `limit`   | 100     | 1500                         |
| `/brands/{id}/insights`      | `limit`   | 100     | 500                          |
| `/brands/{id}/landing-pages` | `limit`   | 100     | 100                          |

<Warning>
  A media call at `limit: 1500` costs **\$1.50**. The cap is high on purpose so
  bulk exports are possible — set `limit` deliberately rather than leaving it to
  chance.
</Warning>

## What you're never charged for

A request that fails validation, authentication, or the credit check costs
nothing. Specifically, every `400`, `401`, `402`, `403`, `404`, `405`, `413` and
`429` is free. Only work that ran is billed.

## The one-row minimum

Three calls run a language model before they touch the database:

* `POST /brands/{id}/media` — both modes
* `POST /brands/search` with `mode: "smart"`

These bill a minimum of one row even when nothing matches, because the model
ran either way. A smart search returning zero brands still costs \$0.0025 — the
response says `"count": 0`, but one row was charged.

`mode: "ids"` and `mode: "brand_name"` don't run a model, and cost nothing when
they match nothing.

## Running out

When the team's monthly credits are exhausted, calls return `402
out_of_credits` and stop doing work. Nothing is queued or partially charged —
add credits or wait for the renewal, and the same request will succeed.

## Insights costs more than it looks

`maxDaysBack` narrows the weekly bucket series, but **not** `totals` — and
`totals` is what you're charged for. It always covers the brand's full
clustering run. Use `limit` to bound the charge; `maxDaysBack` only changes the
shape of the time series.