Search

This page covers the creator search API: its parameters, credentials, result links, limits and spend, search thread turns, shortlist enrichment, and the 402 response.

GET /api/search accepts unsigned callers, browser sessions, Settings API keys, and agent access tokens.

curl "https://www.starcovery.com/api/search?q=slow+morning+coffee"

Try it in the API playground.

ParametersCopy Anchor Link

GET /api/search takes these query parameters:

A value outside these sets returns 400 invalid_query with a message that names the rule and the parameter, such as {"error":"invalid_query","message":"Expected \"ig\" | \"tt\"\n at [\"platform\"]"}. An undeclared parameter is ignored, so a misspelled filter runs the search without that filter.

Send a credentialCopy Anchor Link

Send a credential when you have one:

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.

Link-in-bio URL in resultsCopy Anchor Link

Each result includes the creator's link-in-bio URL as externalUrl when the profile has an http or https URL that does not contain a collected contact address. Contact gating otherwise returns null.

Limits and spendCopy Anchor Link

These grants, rate limits, charges, and timeouts apply to search:

• Unsigned callers search without a credential. Unsigned callers get 100 uses per rolling 24 hours per client IP, and a search is one use. Past that grant, unsigned search returns 402.
• Identified callers get 200 uses per rolling 24 hours per user. Uses past that grant spend prepaid credits.
• A thread turn draws on the same grant: one use for the turn plus one for each search it runs. Pre-claim agent tokens skip the daily grant and spend prepaid credits only.
• Each identified search past the grant spends one prepaid credit. When prepaid credits are empty, identified search returns 402.
• A repeat of a brief and filters spends no grant and no credit when the organization already searched them and that search is still in its search history, or, for an unsigned caller, within 24 hours of the first search of them from the same IP. A brief that calls a model spends on every repeat; Credits and payments lists those briefs.
• Contact addresses stay empty until POST /api/creators/{profileId}/contact. That spend is one credit the first time this organization reveals that profile. Later reveals do not charge again.
• Brief parse (POST /api/search/parse) allows 50 requests per 60 seconds per client IP. Thread turns, shortlist enrichment, and a campaign generate that sends no filters share a limit of 50 per 60 seconds per user. An unsigned thread turn or shortlist enrichment counts against the parse limit of its client IP.
• A thread turn that contains a website address also counts against 10 site reads per 60 seconds on the same key. Past a limit, the route returns 429 with retry-after.
• Search, campaign generate, shortlist enrich, and thread turns hold the request open until the result. The api ends a request at 800 seconds.

Search thread turnsCopy Anchor Link

POST /api/threads opens a search thread for the calling organization and answers its state. POST /api/threads/{threadId}/turns runs the next turn and answers an AI SDK UI message stream (SSE). The caller names the run with a fresh UUID in runId; a run id the thread admitted in the last 24 hours, or one whose turn spent a prepaid credit, answers 409 and changes nothing. Give each new message a fresh id: a message id the thread already stores with the same text runs that message again and replaces its stored reply, and an id the thread stores for another message answers 409 message_taken and runs nothing. A pasted website address is read into a brief; anything else refines the creators on screen: a message that narrows returns a subset of them, a message that asks for more combines a new search with them, and only a message that replaces the search starts over. A question about the organization's campaigns, Lists, credits, or API keys is answered from read tools; with mode set to agent, the turn may also change them, while sending proposals, requesting funding, removing a creator from a campaign, deleting a campaign, List, or file, and revoking an API key wait for the customer's click on the site. Narrowing on followers, average views, engagement, platform, country, or verified status spends nothing; leaving a kind of creator out, such as brand accounts, runs the exclusion judge over the creators on screen and spends one search, billed like GET /api/search. When no filter or search can check a constraint, the reply says so and the brief stays as it was.

The stream contains the site progress, the operations the turn ran, the settled brief and its filters, and the reply. The thread stores each user message when its turn starts and the reply when the turn completes. GET /api/threads/{threadId} answers the thread state: the brief and filters, the stored messages, and activeRun, the run id of the turn still running or null. GET /api/threads/{threadId}/stream replays the running turn from its first chunk and answers 204 when no turn is running. A caller that loses the stream reconnects there while activeRun names the run, and reads the stored reply from GET /api/threads/{threadId} once activeRun is null. POST /api/threads/{threadId}/stop ends the named run at its next stage boundary. A thread the caller does not own answers 404.

GET /api/threads/{threadId}/results answers the creators of the thread result set in the GET /api/search shape, with a shortlist ticket. A refinement stores the set it built; after the first brief, the first read runs one search, billed like GET /api/search, and stores the set. Every later read of a stored set runs no search and spends nothing. A thread with no brief yet answers 404. MCP thread_turn and the CLI thread command run the same loop over the same stream and return the creators of the set in creators.

curl -X POST "https://www.starcovery.com/api/threads" \
  -H "x-api-key: <access_token>"
curl -X POST "https://www.starcovery.com/api/threads/<threadId>/turns" \
  -H "x-api-key: <access_token>" \
  -H "content-type: application/json" \
  -d '{"message":{"id":"m1","parts":[{"text":"creators who post home coffee","type":"text"}],"role":"user"},"runId":"<uuid>"}'

Shortlist enrichmentCopy Anchor Link

A successful search may include a ticket. Pass that ticket with the same creators array and the brief as query to POST /api/search/enrich for niche, celebrity, evidence, and signal analysis (NDJSON stream). Enrichment requires that ticket, charges no credit, and counts against the limit thread turns share; a request past that limit answers 429 and leaves the ticket unspent. MCP enrich_creators and the CLI search --enrich and enrich commands use the same route.

curl "https://www.starcovery.com/api/search?q=coffee" -o search.json
jq '{query: .query.q, ticket, creators}' search.json \
  | curl -X POST "https://www.starcovery.com/api/search/enrich" \
    -H "content-type: application/json" \
    -d @-

When search returns 402Copy Anchor Link

A 402 means the identified daily grant is used and prepaid credits are empty, or the unsigned grant of 100 uses per rolling 24 hours is used.

Identified owners and admins receive a Stripe Checkout URL in checkoutUrl. Pay that session, then retry search. Humans can also buy a prepaid pack from packsUrl. See Credits and payments.