> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.spyglass.so/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.spyglass.so/_mcp/server.

# 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`                    | brand        | \$0.0010 | \$0.10                  |
| `POST /creators`                  | creator      | \$0.0010 | \$0.10                  |
| `GET /account/{id}`               | account      | \$0.0010 | always 1 row — \$0.0010 |
| `POST /media`                     | creative     | \$0.0005 | \$0.05                  |
| `GET /account/{id}/insights`      | cluster      | \$0.0005 | \$0.05                  |
| `GET /account/{id}/campaigns`     | campaign     | \$0.0005 | \$0.05                  |
| `GET /account/{id}/collabs`       | collab       | \$0.0005 | \$0.05                  |
| `GET /account/{id}/landing-pages` | landing page | \$0.0025 | \$0.25                  |
| `POST /account/index`             | —            | free     | —                       |
| `GET /account/{id}/index-status`  | —            | free     | —                       |
| `GET /taxonomies`                 | —            | free     | —                       |
| `GET /team/credit-usage`          | —            | free     | —                       |
| `POST /comments`                  | comment page | \$0.0050 | per page fetched live   |

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 /account/{id}` returns a bare account 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 /account/{id}` needs no cap — it returns one account or `404`.

| Endpoint                      | Parameter | Default | Max                           |
| ----------------------------- | --------- | ------- | ----------------------------- |
| `/brands`, `/creators`        | `limit`   | 20      | 100 (50 for `query` searches) |
| `/taxonomies`                 | `limit`   | 20      | 50                            |
| `/media`                      | `limit`   | 100     | 2000                          |
| `/account/{id}/insights`      | `limit`   | 100     | 500                           |
| `/account/{id}/campaigns`     | `limit`   | 10      | 100                           |
| `/account/{id}/collabs`       | `limit`   | 20      | 100                           |
| `/account/{id}/landing-pages` | `limit`   | 100     | 100                           |

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

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

Two kinds of call are billed a minimum of one row:

* `POST /media`
* `POST /brands` or `POST /creators` searching by `query` (this runs a language
  model)

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

Searches by `ids`, `igUsername`, `tiktokUsername` or `names` don't run
a model and cost nothing when they match nothing.

## Running out

When the team's monthly credits are exhausted, metered 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.
`POST /account/index`, `GET /account/{id}/index-status`, `GET /taxonomies`,
and `GET /team/credit-usage` stay available and are never charged.