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

# Search

> Turn a plain-language brief into a ranked shortlist of real creators, with filters, rate limits, and payment behavior.

`GET /api/search` is the core of the product. It accepts unsigned callers, browser sessions, Settings API keys, and agent access tokens.

```bash theme={null}
curl "https://www.starcovery.com/api/search?q=slow+morning+coffee"
```

Try it live in the [API playground](/docs/api-reference/search-creators).

## Parameters

| Parameter  | Required | Values                                                                                 |
| ---------- | -------- | -------------------------------------------------------------------------------------- |
| `q`        | Yes      | Plain-language brief, 1 to 200 characters.                                             |
| `platform` | No       | `ig` (Instagram), `tt` (TikTok).                                                       |
| `tier`     | No       | `nano` 1K-10K, `micro` 10K-50K, `mid` 50K-250K, `macro` 250K-1M, `mega` 1M+ followers. |
| `country`  | No       | `au`, `br`, `ca`, `de`, `fr`, `gb`, `in`, `jp`, `kr`, `us`.                            |

Unknown parameters or bad values answer 400 with the issues named.

## Identity

Send a credential when you have one:

```bash theme={null}
curl "https://www.starcovery.com/api/search?q=coffee" \
  -H "x-api-key: <access_token>"
```

`Authorization: Bearer <access_token>` works the same. Get a token at [Authentication](/docs/authentication).

## Limits and spend

* Unsigned callers get 50 free searches per UTC day per IP, plus a small per-minute burst. Past the cap: 429 with an `authUrl`.
* Claimed accounts, sessions, and Settings API keys get 100 free searches per UTC day when the prepaid balance is empty.
* Pre-claim agent tokens have no free grant. Their searches spend prepaid credits only, and answer 402 when the balance is empty.
* Each identified search spends one credit (\$0.05) from a non-empty prepaid balance.

## When search answers 402

A 402 means the caller is identified and out of credits. The response carries a `WWW-Authenticate: Payment` challenge (Machine Payments Protocol) so an agent can settle without a human, plus a `packsUrl` for humans. See [Credits and payments](/docs/guides/credits) for the full paid rail, receipts, and failure modes.