Skip to Content
Skip to Content
Starcovery

Quickstart

By Starcovery. Updated .

Run a free Starcovery creator search with no account, get an API key or an OAuth sign-in, narrow the shortlist, and start a campaign.

This page runs an unsigned search, gets a credential, and creates a campaign.

Search before signing up

Search takes a brief. No credential is required for the first call.

curl:

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

CLI:

npx starcovery search searchCreators --q "slow morning coffee"

Unsigned search is free and needs no account and no credit pack. An unsigned caller gets 100 uses per UTC day per IP. An identified caller gets 200 uses per UTC day, and the members of one organization share at most 200 between them. Past either limit, an identified caller spends prepaid credits. A search through the API is one use, and a thread turn is one use plus one for each new search and each exclusion it runs, so a new search typed on the website is two.

Get a credential

A person issues each credential from their Starcovery account.

  • Settings API key: after sign-in, open Settings > API Keys.
  • OAuth access token: an MCP host that supports OAuth signs in when prompted.

Test against the live API

The live test call is the unsigned GET /api/search above. Test calls use the same host as production calls. API versioning covers the versioning and rate-limit headers.

Narrow the shortlist

The q parameter contains the brief. Three optional filters narrow it:

FilterValues
platformig, tt, in any letter case
tiernano 1,000 to 9,999, micro 10,000 to 49,999, mid 50,000 to 249,999, macro 250,000 to 999,999, mega 1,000,000 or more followers; nano+, micro+, mid+, and macro+ mean that tier's lower bound and above, and micro-, mid-, and macro- mean 1,000 up to that tier's upper bound; any letter case, such as Nano+
countryOne or more ISO 3166-1 alpha-2 country codes in either letter case, comma separated, such as us or US, gb, id, mx, or us,ca
curl "https://www.starcovery.com/api/search?q=slow+morning+coffee&platform=ig&tier=nano&country=us"

A value outside these sets returns 400 invalid_query with a message that names the parameter. An undeclared parameter is ignored. Full details: Search.

Use a credential from the CLI

The CLI sends STARCOVERY_TOKEN as Authorization: Bearer on every request:

export STARCOVERY_TOKEN=<api_key>
npx starcovery whoami whoami

Send a Settings API key as Authorization: Bearer <api_key> or as x-api-key on every API call, and an OAuth access token as Authorization: Bearer, or as Authorization: DPoP with a DPoP proof header when the token was issued with a DPoP proof. When Authorization carries a Bearer or DPoP credential, it decides and x-api-key is ignored. See Authentication.

Start a campaign

Create a campaign with a goal, generate matches, then add or remove matches as needed.

curl -X POST "https://www.starcovery.com/api/campaigns" \
  -H "x-api-key: <api_key>" \
  -H "content-type: application/json" \
  -d '{"name": "Coffee", "goal": "quiet morning coffee creators who film at home"}'

See Campaigns and the API reference.

Next steps