# Starcovery documentation > Starcovery is an end-to-end vibe creator marketing product: from one brief it finds, hires, cross-posts, measures, and pays out real Instagram and TikTok creators. This file holds the documentation home page at https://www.starcovery.com/docs and every page in its sidebar except the API reference, in sidebar order, each followed by its URL. The API reference at https://www.starcovery.com/docs/api renders https://www.starcovery.com/openapi.json, and the index of the site is https://www.starcovery.com/llms.txt. # Starcovery developer resources Starcovery developer resources: OpenAPI, MCP, CLI, and agent signup for end-to-end vibe creator marketing with Instagram and TikTok creators. Starcovery runs a creator campaign from a brief: find Instagram and TikTok creators, hire them, cross-post, measure, and pay out. Search ranks creators for the brief and shows sample videos. Agents call search, campaigns, and credits over HTTP, Model Context Protocol (MCP), or the CLI. Humans use the same product from the web. ## Guides and API reference These pages cover the first search, credentials, MCP setup, and the REST endpoints. * [Quickstart](/docs/quickstart): Run an unsigned creator search. No account required. * [Authentication](/docs/authentication): Register an agent identity, or mint a Settings API key. * [MCP](/docs/guides/mcp): Connect Claude, Cursor, Codex, and other MCP clients. * [API reference](/docs/api): REST endpoints with an interactive playground. ## Entry points for each surface Each surface has one entry point. | Surface | Entry point | | --------------------- | ---------------------------------------------------- | | Web | [www.starcovery.com](/) | | REST API | `GET https://www.starcovery.com/api/search?q=coffee` | | MCP (Streamable HTTP) | `https://www.starcovery.com/api/mcp` | | CLI | `npx starcovery search "coffee"` | ## Search spend Search spend depends on the caller. * Unsigned callers need no credential and get 100 uses per rolling 24 hours per IP. * Identified callers get 200 uses per rolling 24 hours per user, then spend prepaid credits. Pre-claim agent tokens spend prepaid credits only. * A search is one use, and a thread turn is one use plus one for each search and each exclusion it runs. Each identified use beyond those 200 spends one prepaid credit. See [Pay for API calls without a subscription](/docs/guides/credits). ## Machine discovery Agents find Starcovery's machine surfaces through these documents and conventions. * OpenAPI 3.1 for REST: [openapi.json](https://www.starcovery.com/openapi.json) * RFC 9727 API catalog: `https://www.starcovery.com/.well-known/api-catalog` * Agent instruction file: [llms.txt](https://www.starcovery.com/llms.txt) * MCP server card: `https://www.starcovery.com/api/mcp/server-card` * Agent skills index: `https://www.starcovery.com/.well-known/agent-skills/index.json` * Protected resource metadata: `https://www.starcovery.com/.well-known/oauth-protected-resource` * Authorization server metadata with the `agent_auth` block: `https://www.starcovery.com/.well-known/oauth-authorization-server` * Markdown for any Starcovery marketing page: append `.md` to the URL, or send `Accept: text/markdown` * JSON envelope for any Starcovery marketing page: append `.json` to the URL. The response is `{ "markdown": "...", "path": "/", "source": "https://www.starcovery.com/" }`. The `.json` suffix rule excludes `/openapi.json`, which returns the OpenAPI document. * HTML responses set an `x-agent-hint` response header that points agents at the `.md` and `.json` page variants and the `/agents` and `/openapi.json` discovery endpoints. URL: https://www.starcovery.com/docs # Quickstart Run an unsigned search, register an identity, and create a campaign. This page runs an unsigned search, registers an identity, and creates a campaign. ## Search before signing up Search takes a brief. No credential is required for the first call. curl: ```bash curl "https://www.starcovery.com/api/search?q=slow+morning+coffee" ``` CLI: ```bash npx starcovery search "slow morning coffee" ``` Unsigned search is free and needs no account and no credit pack. An unsigned caller gets 100 uses per rolling 24 hours per IP. An identified caller gets 200 uses per rolling 24 hours, then spends prepaid credits. A search is one use, and a thread turn is one use plus one for each search and each exclusion it runs. ## Get a credential Both credentials are self-serve. * Agent access token: run `npx starcovery auth register`, or call `POST /agent/identity`. * Settings API key: after sign-in, open [**Settings** > **API Keys**](/home?settings=api-keys). ## 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](/docs/guides/versioning) covers the versioning and rate-limit headers. ## Narrow the shortlist The `q` parameter contains the brief. Three optional filters narrow it: | Filter | Values | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `platform` | `ig`, `tt`, in any letter case | | `tier` | `nano` 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+` | | `country` | Any ISO 3166-1 alpha-2 country code in either letter case, such as `us` or `US`, `gb`, `id`, or `mx` | ```bash 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](/docs/guides/search). ## Register an identity Agents and humans can register without another person in the loop. Short path: ```bash npx starcovery auth register ``` This follows the auth.md protocol, exchanges a service-signed assertion for an access token, saves the credential to `~/.config/starcovery/config.json`, and installs the [host skill](/agents/skill). The same protocol works over plain HTTP. See [Authentication](/docs/authentication). Send the token as `Authorization: Bearer ` or as `x-api-key` on every API call. When `Authorization` carries a `Bearer` or `DPoP` credential, it decides and `x-api-key` is ignored. ## Start a campaign Create a campaign with a goal, generate matches, then add or remove matches as needed. ```bash curl -X POST "https://www.starcovery.com/api/campaigns" \ -H "x-api-key: " \ -H "content-type: application/json" \ -d '{"name": "Coffee", "goal": "quiet morning coffee creators who film at home"}' ``` See [Campaigns](/docs/guides/campaigns) and the [API reference](/docs/api). ## Next steps * [Authentication](/docs/authentication): Agentic signup protocol, claim ceremony, and token exchange. * [Call a creator database over Model Context Protocol (MCP)](/docs/guides/mcp): MCP URL and credential setup for HTTP clients. * [Pay for API calls without a subscription](/docs/guides/credits): Free grants, prepaid packs, and machine payments. * [CLI](/docs/guides/cli): Search, campaigns, credits, and keys from the terminal. URL: https://www.starcovery.com/docs/quickstart # Authentication Register an agent identity, exchange it for an access token, mint API keys, sign in with Google, and optionally claim the account for a human. Starcovery supports agentic registration through the auth.md protocol. An agent can register, receive a credential, and spend without a human present. A human can claim the account later. Humans can also sign up on the web and mint a Settings API key in [**Settings** > **API Keys**](/home?settings=api-keys). Short path: ```bash npx starcovery auth login ``` This opens browser OAuth and saves a refreshable credential. For agentic registration without a human browser: ```bash npx starcovery auth register ``` Use `npx starcovery whoami` to see the current credential, the bound user and organization, and whether the next search uses the user's free grant or the organization's prepaid credits. The rest of this page describes agentic registration over HTTP. ### Discover On a 401 from a gated endpoint (campaigns, keys, billing), read the `WWW-Authenticate` header. It contains `resource_metadata`, which points at the Protected Resource Metadata document. The Model Context Protocol (MCP) endpoint answers 401 to a credential it cannot verify, and to a `tools/call` without a credential for any tool except `search_creators` and `enrich_creators`, with `resource_metadata` at `/.well-known/oauth-protected-resource/api/mcp`. You can also fetch the well-known URLs directly: ```bash curl https://www.starcovery.com/.well-known/oauth-protected-resource curl https://www.starcovery.com/.well-known/oauth-authorization-server ``` The second document contains the `agent_auth` block. `agent_auth.skill` is the live auth.md protocol. `agent_auth.agent_skill` is the host [SKILL.md](/agents/skill). `agent_auth.identity_endpoint` and `agent_auth.claim_endpoint` are the registration and claim URLs below. `identity_types_supported` lists which registration methods the service accepts. ### Use the anonymous identity type The service accepts one identity type: `anonymous`. Other type values return 400 `invalid_body`. ### Register anonymously ```bash curl -X POST https://www.starcovery.com/agent/identity \ -H "content-type: application/json" \ -d '{"type": "anonymous"}' ``` The response contains `registration_id`, a service-signed `identity_assertion` with `assertion_expires`, `pre_claim_scopes`, and claim materials: `claim_url`, `claim_token`, `claim_token_expires`, and `post_claim_scopes`. > The `claim_token` is returned once. Store it if a human may claim this identity later. The `claim_token` and the `identity_assertion` expire 30 days after registration, at `claim_token_expires` and `assertion_expires`, whether or not a human claims the identity. Past that date the identity cannot be claimed or exchanged for an access token. A new registration is a new identity with its own organization, credits, and history. To keep a claimed account, its owner signs in and mints a Settings API key. One client IP registers at most 10 times per rolling 24 hours, and registrations are capped at 100 per UTC day across every caller. Past either cap the endpoint returns 429 with error `rate_limited`; past the daily cap it does so even for a caller that has not registered that day. ### Exchange the assertion for an access token ```bash curl -X POST https://www.starcovery.com/oauth2/token \ -H "content-type: application/x-www-form-urlencoded" \ --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \ --data-urlencode "assertion=" ``` The response is a bearer `access_token` with `expires_in`. When the access token expires, re-run the exchange with the same `identity_assertion`; the exchange returns no refresh token. The assertion works until `assertion_expires`, longer than one access token lasts. Each exchange retires the previous token. Hold one token and re-fetch it when it expires. Access tokens per registration are capped at 10 per rolling hour, the claim grant included. Past the cap the endpoint returns 429 with error `rate_limited`. Honor `Retry-After`. ### Install the host skill Install the Starcovery skill once a credential exists. `npx starcovery auth register` runs this installer for you. HTTP agents run the same installer. If `bun` is on PATH: ```bash bunx skills add https://www.starcovery.com --global --yes --skill starcovery --agent cursor --agent claude-code --agent codex ``` Otherwise: ```bash npx -y skills add https://www.starcovery.com --global --yes --skill starcovery --agent cursor --agent claude-code --agent codex ``` If `bunx`, `npx`, or `skills` fails, the registration remains valid. Never write a token into the skill. Never write a project `.cursor/skills` directory by hand. Claude Desktop has no skills CLI agent id. Download [skill.zip](https://www.starcovery.com/agents/skill.zip) and upload it at **Customize** > **Skills** with code execution on. MCP is a separate connector. See [Call a creator database over MCP](/docs/guides/mcp). ### Call the API ```bash curl "https://www.starcovery.com/api/search?q=space+and+astronomy+explainers" \ -H "Authorization: Bearer " ``` The `x-api-key` header accepts the same token, and is read only when `Authorization` carries no `Bearer` or `DPoP` credential: a request with both headers is answered by `Authorization` alone. MCP accepts the same credential. The MCP tools `search_creators` and `enrich_creators` also work without a credential, and every other MCP tool requires one. See [Call a creator database over MCP](/docs/guides/mcp). ## Claim ceremony (optional) Run the claim only when a human wants to own the account: ```bash curl -X POST https://www.starcovery.com/agent/identity/claim \ -H "content-type: application/json" \ -d '{"claim_token": "", "email": ""}' ``` The response contains a `claim_attempt` block with `verification_uri`, `expires_in`, and `interval`. Starcovery emails a one-time link to the supplied address. The link contains a one-time token. Starcovery uses control of that mailbox to verify a human identity. Tell the person: open the emailed link. On that page they sign in with Google using that email address, then press **Claim This Account**. The account is then theirs. Disposable, reserved, or undeliverable addresses return `undeliverable_email` before initiation. Poll the token endpoint until it stops answering `authorization_pending`, honoring `interval`: ```bash curl -X POST https://www.starcovery.com/oauth2/token \ -H "content-type: application/x-www-form-urlencoded" \ --data-urlencode "grant_type=urn:workos:agent-auth:grant-type:claim" \ --data-urlencode "claim_token=" ``` The claim completes when the person presses **Claim This Account**, before your next poll. From that moment the pre-claim access tokens answer 401 and the pre-claim `identity_assertion` no longer exchanges. The next poll returns a post-claim `access_token` and a fresh `identity_assertion`. Use both from then on. If the claim link window closes, call the claim endpoint again with the same `claim_token` and email address for a fresh link. The new link replaces the previous one immediately. Claim initiation per registration is capped at 3 per rolling 24 hours. Past the cap the endpoint returns 429 with error `rate_limited`. Honor `Retry-After`. ## Scopes Registration returns `pre_claim_scopes` and `post_claim_scopes`. On this service they are the same set, so claiming leaves API access unchanged. Claiming gives a human the account: sign-in, credit packs, and billing. The credential, credits, and history remain in place, and the user id stays the same. ## Credential types The following table lists who mints each credential and where it works. | Credential | Who mints it | Where it works | | ------------------ | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Agent access token | `POST /agent/identity` and the token exchange | REST, MCP, CLI. No free search grant before the claim. | | Settings API key | Humans, in [**Settings** > **API Keys**](/home?settings=api-keys) | REST, MCP, CLI, including `/api/keys`. | | OAuth access token | The OAuth flow of an MCP client or of `starcovery auth login`, after the consent screen | REST and MCP as `Authorization: Bearer`, never as `x-api-key`, and the CLI. Not `/api/keys`. | | Browser session | Web sign-in with Google, or with email and password | web and same-origin API calls. A request whose `Origin` or `Sec-Fetch-Site` header names another origin gets no session from the cookie. | Every credential is bound to one organization. Spend, campaign visibility, and API key ownership all follow that organization. MCP OAuth access tokens and `/api/auth/oauth2/userinfo` include an `organization_id` claim. Authorization embeds the organization that is active at consent time, or the caller's first organization when none is active. An issued token stays bound to that organization when the session's active organization changes. To bind a different organization, pick it under **Give access to** on the consent screen when you authorize. You can also switch the active organization from the **Organizations** menu in the app sidebar before you authorize. Then replace the token. `/api/keys` is the only surface for creating, listing, and revoking Settings API keys. The Better Auth `/api-key/create`, `/api-key/delete`, `/api-key/get`, `/api-key/list`, `/api-key/update`, and `/api-key/verify` routes are disabled and respond 404. Send API key requests to `/api/keys` with a browser session or a Settings API key. An owner or admin lists and revokes every key of the organization. A member lists and revokes only the keys that member minted, and a revoke of another member's key returns 404. Humans sign in on the web with Google, or with an email address and a password at [Sign in](/sign-in). A password account confirms its email address through a mailed link before it can sign in. [Forgot password](/forgot-password) mails a reset link. Google is a trusted Better Auth provider. If a Google account's verified email matches an existing user whose email is already verified, Starcovery links the Google identity to that account instead of creating a duplicate. This linking leaves agent access tokens, Settings API keys, and OAuth access tokens unchanged. ## Docs playground The [API playground](/docs/api) starts with no credential. Paste a Settings API key or an agent access token into its authentication panel. URL: https://www.starcovery.com/docs/authentication # Write a creator brief Describe what the creators post in one sentence, name the platform, home country, and follower size in words, and refine the results in a Thread. To write a creator brief, describe in one sentence what the creators post and who your audience is, then name the platform, the creators' home country, and the follower size in words. Starcovery sets those three filters from your words, ranks creators for the brief, and lets you refine the results in a Thread on [/app](/app). This page covers the steps, four example briefs with the filters each one yields, what each step costs, and the questions marketers ask. ## Steps ### Describe what the creators post Name the niche and the content, such as "creators who film espresso recipes at home", and add the audience your business sells to when it matters, such as "for hobbyist baristas". A brief is up to 200 characters. On /app, a first message that is longer becomes one brief of one sentence under 200 characters. Describe what a video shows. Words about views, engagement, rates, or audience demographics are not checked as filters. Narrow on views and engagement after the first search, as [Refine in the Thread](#refine-in-the-thread) describes. ### Name the platform, country, and follower size Starcovery reads three filters from a first brief: | Filter | Words that set it | Values | | --------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Platform | "on Instagram", "TikTok creators" | Instagram, TikTok | | Country | The creators' home country, or a city in it: "UK based", "Korean creators", "creators in Indonesia", "in Los Angeles" | Every country | | Followers | A tier name, a follower count, or an open-ended count at a tier bound | Nano 1K to 10K, Micro 10K to 50K, Mid 50K to 250K, Macro 250K to 1M, Mega 1M+ | A follower count sets the tier that contains it: "around 100K followers" is Mid. An open-ended count at a tier bound sets every tier on that side: "more than 10K followers" is Micro+ 10K+, and "under 50K followers" is Up to 49,999 followers. Any other open-ended count, such as "over 100K followers", sets no follower filter. Country means where the creators live. Words about the audience, such as "for a US audience" or "targeting UK fans", set no country, because no filter checks where an audience lives. A place where the creators do not sell, such as "not selling products in Korea", sets no country either; write "skincare creators in Korea not selling products" for creators who live there. A brief that asks for another platform, such as YouTube or Twitch, sets no platform, and the reply says that Starcovery has only Instagram and TikTok creators. The **Brief** row leaves the words that asked for that platform out, as it does for Instagram or TikTok. ### Leave out what you do not want Start the part to leave out with exclude, excluding, except, or without, such as "home cafe creators, excluding coffee shops and sponsored posts". Starcovery reads each creator's profile and sample videos and drops the creators that part names. When without names how the content is made, as in "baking without sugar", it stays part of what you want. Ask for real people, indie creators, or individual creators to leave out brand, business, and organization accounts, and creators whose sample videos are mostly sponsored posts or ads. Only exclude, excluding, except, and without start a part to leave out. A brief that says "not" keeps those words in the description of the creators you want. ### Run the brief Type the brief in the composer on [/app](/app) and choose **Send**. To start from your company website instead, paste its address, and the Thread drafts a brief from the site. The Thread shows a **Search plan** card with the **Brief**, **Platform**, **Country**, and **Followers** it searches, and a chip in the composer for each filter the search has. The **Brief** row holds the words that describe the creators, without the words that set the platform, the country, or the follower size, such as "coffee creators" for "UK based coffee creators around 100k followers on Instagram", because the other rows state those filters. **Instagram and TikTok**, **Anywhere**, and **Any size** mean the search has no platform, country, or follower filter, so they get no chip. To drop a filter the brief set by mistake, remove its chip once the turn finishes, and the results reload without it and keep every other filter and narrowing the Thread holds. When the search has no country filter, the composer shows a **Country** button beside the filter chips. It opens a searchable list of every country with its flag. Typing matches country names, codes, and other names, and tolerates near misses, so "korea" finds Korea, "uk" finds United Kingdom, and "indo" finds Indonesia. Choose a country to set the country filter: the Thread adds the line "Set the country filter to Indonesia." with a **Search plan** card, and the results reload with the filter, the same way removing a chip reloads them without it. ### Refine in the Thread Send the next message in the Thread composer, **Refine or paste a site**: * A message that narrows, with words such as only, of these, above, or below, keeps a subset of the creators on screen. It narrows on follower tier, average views, engagement on views, platform, home country, verified accounts, or the best-fit few. Average views and engagement come from up to 6 of each creator's newest posts with a video, fewer when the creator has fewer such posts. * A message that leaves a kind of creator out, such as "not brand accounts", reads the creators on screen and drops that kind. The Search plan **Brief** keeps its earlier words and gains the exclusion at its end, such as ", excluding brand accounts". With no creators on screen there is nothing to leave out, so the reply says so and the search stays as it is. * A message that asks for more creators, or for another kind as well, runs a new search and adds its creators to the ones on screen, and when the two sets together pass 50 creators, each keeps an equal share of its best fit creators. The reply states how many creators the search added, says so when it added none, and states how many creators that were on screen the new list leaves out. A message that asks for more creators like the ones on screen, such as "more creators like these", and names no new kind, keeps the search the Thread already holds. A message that asks only to add a platform the search already covers, and nothing else, such as "also TikTok creators" on a search on Instagram and TikTok, or on TikTok alone, runs no search and changes nothing: the reply says that the search already covers TikTok, and the creators on screen, the Search plan, and the count line stay as they are. A message that narrows to that platform, such as "only TikTok creators", still narrows the creators on screen, and one that asks for more creators on it, such as "more TikTok creators like these", still runs a search. * A message that replaces the search starts over. A message that asks for a new search and asks for no more creators and no other kind as well, such as "run a new search for coffee creators in Mexico", replaces the search, and the new search takes its platform, country, and follower tier only from the message, except that a switch to the other platform or a follower tier replacement keeps the other filters of the running search. A message that narrows, leaves a kind out of the creators on screen, or runs a new search adds a **Search plan** card that states the search the Thread holds after that message: the brief, the filters, and a row for each narrowing on average views, engagement, verified accounts, or the best-fit few. A message that only narrows the creators on screen runs no search and still adds a card, also when it keeps none of them: the card shows the new value when the message sets one, and repeats the earlier values when it does not. Later messages keep those narrowings: removing a chip, switching the platform, replacing the follower tier, or asking for more creators like these keeps them on every creator the new search adds. A message that the reply alone answers adds no card. Neither does a message that leaves a kind out when no creators are on screen: the search did not change, so there is no new search to state. A message that narrows the creators on screen to a home country, such as "only creators based in Mexico", filters them on that country. The results keep the creators who live there, and the list is empty when none of them does, such as "only creators based in the UK" over a Brazil search; the reply says that none of the creators on screen lives there. The **Search plan** card that message adds reads that country, and the composer shows its chip. The card of a later message that narrows those creators again without naming a country reads it too. A message that switches to the other platform of a search that has one, such as "only TikTok creators" after an Instagram search, replaces the search with one on the new platform that keeps the brief and the other filters. A message that adds the other platform, such as "also TikTok creators", keeps the creators on screen and adds the new platform's creators to them, and when the two sets together pass 50 creators, each keeps an equal share of its best fit creators. Its card reads **Instagram and TikTok**. A later "only Instagram creators" narrows the creators on screen back to Instagram, and its card reads **Instagram** beside the same brief. A message that asks for a new search in a country, such as "run a new search for coffee creators in Mexico", runs the search with that country as its country filter, and the composer shows the **Mexico** chip. Followers narrow by tier only. For a count that is no tier bound, such as "over 100K", the reply names the nearest tier. A tier that shares no follower count with the tier of the Search plan, such as "only micro creators" over Mid 50K to 250K results, narrows nothing, so the Thread runs a new search for that tier and keeps the brief, the platform, and the country. When no filter or search can check what you ask, such as follower age, the reply says so and the results stay as they are. **New Thread** starts another Thread for a new brief. ### Save the creators Select creators, then choose **Hire These Creators** to start a campaign with them, or **Save as List**. Signed out, **Hire These Creators** asks you to sign in. See [Campaigns](/docs/guides/campaigns) and [Pay creators and handle disclosure](/docs/guides/pay-creators). ## Example briefs The first three briefs set every filter they name. The **Search plan** card shows these values, and its **Brief** row reads the brief's other words, such as "coffee creators" for the first one: | Brief | Platform | Country | Followers | | ------------------------------------------------------------------------ | -------------------- | -------------- | ---------------------- | | UK based coffee creators around 100k followers on Instagram | Instagram | United Kingdom | Mid 50K to 250K | | nano creators in France posting street food | Instagram and TikTok | France | Nano 1K to 10K | | fitness creators on TikTok in the United States with under 50k followers | TikTok | United States | Up to 49,999 followers | The fourth brief loses what it asks for: | Brief | Platform | Country | Followers | | ------------------------------------ | -------------------- | -------- | --------- | | skincare creators with a US audience | Instagram and TikTok | Anywhere | Any size | "With a US audience" names where the audience lives, which no filter checks, so the search covers creators in every country. When the creators should live in the United States, write "US based skincare creators". ## Live example Each example brief builds on the brief of a published search page. [coffee creators](/search/coffee-creators) is the published search page for the brief "coffee creators", with no filter. It lists the ranked creators with each one's platform, followers, average views, and engagement on views. Each creator name opens the creator page, such as [@jameshoffmanncoffee](/tt/@jameshoffmanncoffee). **Run This Search** runs the brief on [/app](/app?q=coffee+creators), where a follow-up such as "only Instagram creators based in the UK" narrows it. The other examples start from [street food](/search/street-food), [fitness creators](/search/fitness-creators), and [skincare creators](/search/skincare-creators). ## Prices Each step spends uses of the daily grant: 100 per rolling 24 hours per IP without an account, and 200 per user signed in. Signed in, each use past the grant spends one credit, and a credit costs $0.05. | Step | Price | | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Run a first brief on /app, or as the first message to the assistant on another page | 1 use for the Thread turn, plus 1 search, or up to 2 searches when the brief names a platform, country, or follower size | | Narrow the creators on screen | 1 use for the turn, and no search | | Leave a kind of creator out | 1 use for the turn, plus 1 for the exclusion. With no creators on screen nothing is left out, so no exclusion runs or spends and the brief stays as it was | | Ask for more creators, or replace the search | 1 use for the turn, plus each search it runs, up to 3 | | Remove a filter chip | 1 search when the results reload, or the price of a repeat in the next row when you already searched the brief with the filters that remain | | Choose a country with **Country** | 1 search when the results reload, or the price of a repeat in the next row when you already searched the brief with that country filter | | Repeat a brief and filters you already searched | 1 use for the turn. The search is free while the first one is in your search history, or for 24 hours from the same IP without an account | A search past the grant, a contact reveal, and a private campaign each spend 1 credit. Prepaid credit packs are on [Pricing](/pricing). See [Pay for API calls without a subscription](/docs/guides/credits) for the full cost table. ## Frequently asked questions ### What should a creator brief include? What the creators post, who your audience is, and, when they matter, the platform, the creators' home country, and the follower size. One sentence of up to 200 characters. ### Is this the brief I send to creators? No. In Starcovery, a brief describes the creators you want to find. Creators read the proposal: what they post, the pay per creator, the creator posting date, and the disclosure statement. See [Pay creators and handle disclosure](/docs/guides/pay-creators). ### How do I find creators in a specific country? Name the creators' home country or a city in it, such as "UK based", "creators in Indonesia", or "in Seoul", and the brief sets that country's filter. Once the Thread has a search with no country filter, choose **Country** in the composer and pick the country, or send a follow-up such as "only creators based in Mexico", which narrows the creators on screen by home country. ### Can I search for creators whose audience is in the US? No. No filter checks where an audience lives. Words such as "for a US audience" stay in the brief and set no country. ### How do I search by follower count? Write a tier name, such as "micro creators", or a follower count, such as "around 100K followers". "More than 10K" and "under 50K" set every tier on that side of the bound. A count that is no tier bound, such as "over 100K", sets no follower filter. ### Can I filter creators by engagement rate or views? Yes, after the first search. Send a follow-up such as "only those above 100K average views" in the Thread. The brief itself does not check views or engagement. ### How do I exclude brand accounts? Ask for real people, indie creators, or individual creators in the brief, or send "not brand accounts" in the Thread. ### Can I search YouTube creators? No. Starcovery has only Instagram and TikTok creators, and a brief that asks for another platform searches both. ### Can I write a brief in another language? Yes. The brief runs as typed. Exclude, excluding, except, without, real people, indie creators, and individual creators work in English only. ### What does a creator brief cost? A first brief on /app, or sent to the assistant on another page, is one Thread turn: 1 use for the turn plus 1 or 2 searches, from the daily grant and then 1 credit each. See [Prices](#prices). URL: https://www.starcovery.com/docs/guides/creator-brief # Search Query the Starcovery creator search API with briefs, platform and tier filters, rate limits, credit spend, and 402 payment flow. 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. ```bash curl "https://www.starcovery.com/api/search?q=slow+morning+coffee" ``` Try it in the [API playground](/docs/api). ## Parameters `GET /api/search` takes these query parameters: | Parameter | Required | Values | | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `q` | Yes | The brief, 1 to 200 characters. | | `platform` | No | `ig` (Instagram), `tt` (TikTok), in any letter case, such as `tt` or `TT`; the search reads it as its lowercase code. | | `tier` | No | `nano` 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 reads as the lowercase tier, so `Nano+` reads as `nano+`. | | `country` | No | Any ISO 3166-1 alpha-2 country code in either letter case, the country where the creator is based, such as `us` or `US`, `gb`, `id`, or `mx`, or `xk` for Kosovo; the search reads it as its lowercase code. An unknown code returns 400 `invalid_query` with the message `Expected an ISO 3166-1 alpha-2 country code, such as us or id`. | 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. The search reads its filters from `platform`, `tier`, and `country` alone, never from the words of the brief. A brief such as `UK based coffee creators around 100k followers on Instagram` sent with no other parameter runs with no filter, so its creators span Instagram and TikTok and every country. `POST /api/search/parse` reads the filters out of a brief, `{"country":"gb","platform":"ig","tier":"mid"}` for that one, for you to send with the search; `/app` does this on its own for a typed brief. ## Send a credential Send a credential when you have one: ```bash curl "https://www.starcovery.com/api/search?q=coffee" \ -H "x-api-key: " ``` `Authorization: Bearer ` works the same. Get a token at [Authentication](/docs/authentication). ## Link-in-bio URL in results 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 spend 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 and each exclusion 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. [Pay for API calls without a subscription](/docs/guides/credits) has the full cost table. * 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 turns `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`, and nothing when no creators are on screen. 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, `activeRun`, the run id of the turn still running or stopping, or null, and `turns`, the run id and state of each turn the thread admitted. `GET /api/threads/{threadId}/stream` replays the open turn from its first chunk and answers 204 when no turn is open. The stream ends after the turn has stored its reply. 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` closes the named run to new searches, exclusions, and tool calls. A run that has started none of them ends with no reply. A run that has started one lets it finish and completes its reply from what it has, and its stream runs on until that reply is stored. 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`. ```bash curl -X POST "https://www.starcovery.com/api/threads" \ -H "x-api-key: " curl -X POST "https://www.starcovery.com/api/threads//turns" \ -H "x-api-key: " \ -H "content-type: application/json" \ -d '{"message":{"id":"m1","parts":[{"text":"creators who post home coffee","type":"text"}],"role":"user"},"runId":""}' ``` ## Shortlist enrichment 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. ```bash 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 402 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 [Pay for API calls without a subscription](/docs/guides/credits). URL: https://www.starcovery.com/docs/guides/search # Find creators who post about a topic Type the topic as a brief at /app, and Starcovery ranks Instagram and TikTok creators by the videos they post about it. To find creators who post about a topic, type the topic as a brief at [/app](/app), such as `home espresso tutorials`. Starcovery ranks Instagram and TikTok creators by the videos they post, and each match shows the videos you watch to check the fit. You need no account and no card to search. Sign in to save creators, add them to a campaign, or reveal a contact address. ## Write the topic as a brief A brief describes what the videos are about, in the words you use for the posts you want: * `home espresso tutorials` * `slow morning coffee` * `coffee creators in Seoul` Add the platform, the follower range, or the country to the brief when they matter, such as `home espresso tutorials on TikTok`. Starcovery applies them as filters. The country filter covers every country and means where the creator is based. ## Why the search reads the posts, not the bio Starcovery ranks each creator by the videos they post that match the brief. The bio does not set the rank. A creator whose bio names no topic ranks for `home espresso tutorials` when their videos are espresso tutorials. A bio that names coffee does not lift a creator whose videos are about something else. Each match shows the videos that matched, so you check the fit by watching them. The fit score, from 0 to 1, is the relevance of the creator to the brief. ## Find the creators ### Type the brief Open [/app](/app), type the topic, and send it. The brief starts a Thread that keeps the brief, the filters, and the creators on screen. ### Watch the videos Results open on **Reels**: one tile per creator with the video that best matches the brief. **Creators**, **Table**, and **Map** show the same creators as cards, as a table, and on a map. Each creator links to a creator page with recent posts, average views, and engagement. ### Narrow the results Type a follow-up in the assistant pane, such as `only creators with more than 10,000 followers` or `leave out brand accounts`. A message that narrows by followers, average views, engagement, platform, country, or verified status keeps a subset of the creators on screen. A message that leaves a kind of creator out checks the creators on screen and runs one search. ### Save and contact Select creators, then choose **Save as List** or **Add to Campaign**. For a creator with a contact address on file, **Reveal Contact** on the creator page shows the address to your organization. ## See a published search [Creators matching "home espresso tutorials"](/search/home-espresso-tutorials) is a published search page: the creators from a saved search for that brief, each with sample videos and a link to the creator page at `/tt/@` or `/ig/@`. **Run This Search** opens the same brief at [/app](/app) with current results. The Markdown rendition at `/search/home-espresso-tutorials.md` lists each creator's platform, followers, and fit score. Published searches on nearby coffee topics: * [coffee](/search/coffee) * [coffee creators](/search/coffee-creators) * [slow morning coffee](/search/slow-morning-coffee) * [coffee syrup](/search/coffee-syrup) * [coffee creators in Seoul](/search/coffee-creators-in-seoul) `/search-sitemap.xml` lists every published search page. An agent runs the same search with `GET /api/search?q=home+espresso+tutorials`, described in [Search](/docs/guides/search). ## What each step costs A search is one use, and an assistant turn is one use plus one for each search and each exclusion it runs. Without an account, you get 100 uses per rolling 24 hours per IP address. Signed in, you get 200 uses per rolling 24 hours, and each use past that spends one prepaid credit. A credit costs $0.05. | Step | Cost | | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | Send the brief at /app | One use for the turn, plus one for each search or exclusion it runs | | Narrow by followers, average views, engagement, platform, country, or verified status | One use for the turn | | Leave a kind of creator out | One use for the turn, plus one for the exclusion | | Watch videos and open creator pages | Free | | **Save as List** | Free | | **Reveal Contact** | 1 credit the first time your organization reveals that profile | [Pay for API calls without a subscription](/docs/guides/credits) lists every charged action, and [pricing](/pricing) lists the prepaid packs. ## Questions about finding creators by topic ### How do I find TikTok creators who post about coffee? Type `coffee on TikTok` at [/app](/app). Starcovery ranks TikTok creators by their coffee videos. Name the kind of coffee post for a closer match, such as `home espresso tutorials on TikTok`. ### How do I find Instagram creators in a niche? Describe the niche as the posts you want, such as `sensitive skin reels on Instagram`, at [/app](/app). Starcovery ranks Instagram creators by those videos. ### Do I need hashtags or keywords from the bio? No. Write the topic as you would say it. The rank comes from the videos, not from the bio. ### How do I find micro creators who post about a topic? Add the size to the brief, such as `micro creators who post home espresso tutorials`, or narrow the results in the assistant pane. Micro creators have 10,000 to 49,999 followers. ### How do I find creators in one country? Add the country to the brief, such as `coffee creators in Japan`, or narrow the results in the assistant pane. The country filter covers every country. When a search has run with no country filter, choose **Country** beside the filter chips to pick one. ### How do I check that a creator fits before I contact them? Watch the matched videos on the result tile, then open the creator page for recent posts, average views, and engagement. Revealing the contact address spends 1 credit the first time your organization reveals that profile. ### Is searching by topic free? Yes, within the daily allowance: 100 uses per rolling 24 hours per IP address without an account, and 200 signed in. Signed in, each use past the allowance spends one prepaid credit. URL: https://www.starcovery.com/docs/guides/find-creators-by-topic # Find micro creators for a skincare launch Search Starcovery for skincare creators with 10,000 to 49,999 followers, read the fit score, shortlist them, and send proposals, with the price of each step. To find micro creators for a skincare launch, write one brief on [/app](/app) that names the product, the content, and a follower size of 10,000 to 49,999, such as `skincare creators who film their morning routine, 10,000 to 49,999 followers`. Starcovery returns Instagram and TikTok creators whose videos match the brief, and you add the ones you want to a campaign and send them a proposal. In Starcovery, a micro-influencer is a creator in the **Micro** follower tier. This page covers the tiers, the search steps, the fit score, a live example, the price of each step, and common questions. ## Follower tiers Starcovery lists creators with 1,000 or more followers and sorts them into these tiers: | Tier | Followers | | ----- | ------------------ | | Nano | 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 | ## Steps ### Write the brief On [/app](/app), describe the creators: the product, what the videos show, and the follower size. A message of up to 200 characters runs as the brief, and Starcovery rewrites a longer message, up to 2,000 characters, into a brief under 200 characters. These briefs name the Micro tier: * `skincare creators who review vitamin C serums, 10,000 to 49,999 followers` * `TikTok creators who film sunscreen reviews, 10,000 to 49,999 followers` * `US creators with sensitive skin and 10,000 to 49,999 followers` ### Check the filters Starcovery reads the platform, the creator's country, and the follower tier from the brief and shows each one as a chip. A Micro brief shows **Micro 10K to 50K**. Remove a chip to search without that filter. When no tier chip appears, send a follow-up message such as `only creators with 10,000 to 49,999 followers`. The follow-up narrows the creators on screen and runs no new search. ### Read the results Results open in the **Reels** view. **Creators** shows one card per creator with each handle and its followers, engagement on views (likes plus comments per view), and average views. **Table** sorts by **Followers**, **Average views**, or **Engagement on views**. Select a handle to open the creator page. ### Shortlist the creators Select the checkbox on each creator you want. The selection bar offers these actions: * **Hire These Creators** starts a campaign with the selected creators and opens it. * **Save as List** saves the creators, with the brief and filters, to a List. * **Add to Campaign** adds the creators to a campaign you already have. * **Export CSV** downloads the selected creators. Signed out, **Hire These Creators** and **Save as List** ask you to sign in. ### Send proposals On the campaign's **Proposal** page, set **What they post**, **Pay per creator**, the **Creator posting date**, and the **Disclosure statement**, then select **Save Proposal**. On the campaign page, select **Send Proposal**. The Starcovery team sends the proposals from its staff queue. A send needs a draft campaign, a saved proposal, a creator posting date that is today or later in UTC when one is set, a disclosure, and at least one creator with 1,000 or more followers. [Campaigns](/docs/guides/campaigns#send-and-funding-requests) lists every rule. ## Fit score The fit score is a number from 0 to 1 that rates how closely a creator's best-matching video matches the brief. A higher score is a closer match. Starcovery ranks results by the fit score times an engagement factor from the creator's videos and follower count. The cards on [/app](/app) show no fit score. The score is the `fitScore` field of each result from [REST](/docs/guides/search), [MCP](/docs/guides/mcp), and `starcovery search --json` in the [CLI](/docs/guides/cli). The CLI table shows it in the **Fit** column from 0 to 100. A published search page's Markdown form, which you read by adding `.md` to the page's path, shows it in the **Fit** column. ## Live example These published searches ran skincare briefs without a follower tier. Each page lists up to 12 creators, links each creator page, and has **Run This Search**, which runs the brief on [/app](/app): * [skincare creators](/search/skincare-creators) * [sensitive-skin reels](/search/sensitive-skin-reels) * [sunscreen](/search/sunscreen) * [cleansing balm](/search/cleansing-balm) On October 6, 2026, these creators on those pages were in the Micro tier: [@lorealistar](/tt/@lorealistar) and [@morgannllee](/tt/@morgannllee) on skincare creators, [@jade.tanis](/tt/@jade.tanis) on sensitive-skin reels, and [@mcrae_hynd](/tt/@mcrae_hynd) on cleansing balm. Follower counts change, so a creator page can show another tier later. To see only micro creators, add the follower size to the brief on [/app](/app). ## Price A credit costs $0.05. Buy credit packs on [Pricing](/pricing). | Step | Cost | | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Search, signed out | Free for 100 uses per rolling 24 hours per IP | | Search, signed in | Free for 200 uses per rolling 24 hours per user, then 1 credit each | | Follow-up message | 1 use for the message, plus 1 for each search or exclusion it runs, at most 3 | | Follow-up that narrows by followers, views, engagement, platform, country, or verified status | 1 use for the message, no search | | Save as List, Add to Campaign, Hire These Creators, Export CSV | Free | | Private campaign | 1 credit at creation, or when a public campaign becomes private | | Reveal a creator's contact | 1 credit the first time your organization reveals the profile | | Send Proposal | Free | Creator pay is separate from credits. When creators accept, you fund **Pay per creator** for each of them plus a platform fee that your market information answer sets: none, 1% to 18%, or 20%. [Pay for API calls without a subscription](/docs/guides/credits) lists every credit cost, and [Campaigns](/docs/guides/campaigns) lists the fee rules. ## FAQ ### How many followers does a micro creator have? 10,000 to 49,999 followers. A creator with 1,000 to 9,999 followers is in the Nano tier, and Mid starts at 50,000. ### How do I find skincare creators on TikTok only? Name TikTok in the brief, such as `skincare creators on TikTok with 10,000 to 49,999 followers`. A **TikTok** chip confirms the filter. Starcovery searches Instagram and TikTok. ### How do I find skincare creators in one country? Name where the creators are based, such as `skincare creators in the US`. The country filter means the creator's home country. A phrase about the audience, such as `for a US audience`, stays in the brief and sets no country filter. The filter covers every country. ### How do I check a creator's engagement before I reach out? Each card shows engagement on views and average views. **Table** sorts by either one. The creator page shows the creator's videos. ### How do I get a creator's email address? Open the creator page and select **Reveal Contact**. The first reveal of a profile costs your organization 1 credit, and later reveals are free. A card shows **Email on file** when Starcovery has an address your organization has not revealed, and **Email revealed** after a reveal. ### Can I search without an account? Yes. Signed out, [/app](/app) allows 100 uses per rolling 24 hours per IP. Saving a List, starting a campaign, and revealing a contact need an account. URL: https://www.starcovery.com/docs/guides/skincare-launch # Run a creator campaign without an agency Describe the campaign, pick creators, send the proposal, and fund the creators who accept, while the Starcovery team sends the proposals and pays the creators. To run a creator campaign without an agency, describe the campaign in Starcovery, pick the creators for its Shortlist, write the proposal, and choose **Send Proposal**. The Starcovery team sends the proposals, invoices your organization for the creators you fund, and pays each funded creator after they post. This page covers each step from brief to payout, who takes each step, what each step costs, a live example, and common questions. ## Steps ### Describe the campaign Choose **New Campaign** and paste your company website, or describe the creators you want. Starcovery finds creators whose reels already fit on the [web](/app). Select the ones you like: **Hire These Creators** starts a campaign with them, and **Add to Campaign** adds them to a campaign you already have. **Save as List** saves them to a List, and the List page offers **Add to Campaign** later. ### Edit the Shortlist The **Creators** section of the campaign page is the campaign's Shortlist. **Add Creators** opens a search for the campaign, and **Remove** takes a creator off the Shortlist. The Shortlist stays editable until you choose **Send Proposal**. ### Write the proposal Choose **Write the Proposal**. On the **Proposal** page, set **What they post**, the platforms the one payment covers, **Pay per creator** in whole dollars, the **Creator posting date**, and the **Disclosure statement**. **What the creator sees** shows the proposal as each creator reads it. Under **More Options**, set the visibility and the **Declassifying date**. On a public campaign, signed-in visitors read the campaign details from that date. ### Send the proposal Choose **Send Proposal**. The request goes to the Starcovery team, who send the proposals from the staff queue. The campaign needs a contract, a disclosure statement, and at least one creator with 1,000 or more followers. A creator posting date, when set, needs to be today or a later day in UTC. Once Starcovery starts sending, the contract and the disclosure statement are locked. ### Read the answers Each creator accepts or declines. The **Creators** section shows each creator's answer. ### Fund the creators who accepted Choose **Fund Creators**, answer the market information question if you have not answered it, and choose **Request Funding**. The answer sets the platform fee, as [Prices](#prices) lists, and locks while a funding request is open or the campaign holds funds. **Campaign funding** offers all three answers, including a hold of up to 18 months. The request covers the creators who accepted and are not yet funded: the pay per creator times those creators, plus the platform fee. The Starcovery team emails an invoice for that amount, and the campaign is funded once the invoice is paid. Only an owner or admin of the organization requests funding. ### Creators post and get paid Each funded creator posts, by the creator posting date when one is set. Starcovery records each live post on the campaign, one per platform, with its view count and engagement count. After a funded creator posts, the Starcovery team pays that creator. The campaign shows **Paid out.** once every funded creator is paid. Over REST, create the campaign with `POST /api/campaigns` and a `goal`, store ranked matches with `POST /api/campaigns/{campaignId}/generate`, and edit them with `POST /api/campaigns/{campaignId}/matches` and `DELETE /api/campaigns/{campaignId}/matches/{matchId}`. Set `contract`, `disclosure`, and `marketInformation` on the create or with `PATCH /api/campaigns/{campaignId}`, then call `POST /api/campaigns/{campaignId}/send` and `POST /api/campaigns/{campaignId}/fund`. Funding needs the `marketInformation` answer. The same steps work over [MCP](/docs/guides/mcp) and the [CLI](/docs/guides/cli). See [Campaigns](/docs/guides/campaigns), and [Pay creators and handle disclosure](/docs/guides/pay-creators) for the disclosure statement and the creator's payout account. ## Who takes each step | Step | Who | | ------------------ | -------------------------------------- | | Pick creators | You | | Write the proposal | You | | Send the proposals | The Starcovery team | | Accept or decline | Each creator | | Request funding | An owner or admin of your organization | | Pay the invoice | Your organization | | Post | Each funded creator | | Pay the creators | The Starcovery team | ## Live example [coffee creators](/search/coffee-creators) is a published search page: a ranked list of creators for the brief "coffee creators", each with platform, followers, average views, and engagement on views. Each creator name opens the creator page, such as [@jameshoffmanncoffee](/tt/@jameshoffmanncoffee) on TikTok and [@orenmeetsworld](/ig/@orenmeetsworld) on Instagram. To run a campaign from it, run the brief on the [web](/app?q=coffee+creators), select the creators you want, and choose **Hire These Creators**. Then follow the steps above from [Write the proposal](#write-the-proposal). A creator page with 1,000 or more followers shows **Hire**, which starts a campaign with that one creator. ## Prices A credit costs $0.05. Send Proposal and the funding request spend no credits. Each signed-in user gets 200 uses per rolling 24 hours as the daily grant. | Step | Price | | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | | Search within the daily grant | Free | | Search past the daily grant | 1 credit | | Thread turn | 1 use, from the daily grant and then 1 credit, plus up to 3 searches and exclusions in all, each billed like a search | | Campaign generate | One search, billed like a search | | Private campaign | 1 credit at creation, or when a public campaign becomes private | | Creator pay | The pay per creator, for each funded creator | | Platform fee, market information answer **Yes** | None | | Platform fee, answer **Not for up to 18 months** | 1% to 18% of the creator pool, one percent per month held | | Platform fee, answer **No** | 20% of the creator pool | The creator pool is the pay per creator times the funded creators. For example, three creators at $200 each make a $600 pool. The answer **No** adds a $120 fee, for an invoice of $720. Prepaid credit packs are on [Pricing](/pricing). See [Pay for API calls without a subscription](/docs/guides/credits) for the credit ledger. ## Frequently asked questions ### How do I run a creator campaign without an agency? Paste your website or describe who you want with **New Campaign**, pick the creators, write the proposal, and choose **Send Proposal**. The Starcovery team sends the proposals, and pays each creator you fund after they post. ### How do I find creators for a brand campaign? Describe the creators you want on the [web](/app). Starcovery ranks Instagram and TikTok creators for the brief by fit score. See [Search](/docs/guides/search). ### How do I send a creator a paid partnership offer? Write the proposal on the campaign, then choose **Send Proposal**. The Starcovery team sends it to each creator on the Shortlist. ### How much does a creator campaign cost? The pay per creator for each funded creator, plus the platform fee your market information answer sets, plus credits for searches past the daily grant and for a private campaign. See [Prices](#prices). ### Who pays the creators, and when? The Starcovery team, after each funded creator posts. You pay the Starcovery invoice for the creators you fund. ### Can I keep the campaign private? Yes. New campaigns are public by default. Making a campaign private costs 1 credit, at creation or when you change a public campaign to private. ### Can an AI agent run the campaign for me? Yes. An agent creates the campaign, edits its matches, and requests the send and the funding over MCP, REST, or the CLI. The Starcovery team sends the proposals and pays the creators. URL: https://www.starcovery.com/docs/guides/run-a-creator-campaign # Campaigns Create a campaign, generate matches, add or remove creators, and export the shortlist. This page covers how to create a campaign, generate and edit its matches, request a send or funding, and control who reads it. A campaign stores a goal, generated creator matches, and the shortlist you edit. Campaign endpoints work from the web app, Model Context Protocol (MCP), the REST API, and the CLI. All campaign endpoints require a credential: an agent access token, a Settings API key, an OAuth access token, or a browser session. Send an agent access token or a Settings API key as `x-api-key` or `Authorization: Bearer`, and an OAuth access token as `Authorization: Bearer`. See [Authentication](/docs/authentication). Set the contract, creator posting date, campaign details declassifying date, and disclosure, then request a Send Proposal. The Starcovery team sends the proposals from its staff queue and handles funding, as described in [Send and funding requests](#send-and-funding-requests). ## Create and manage a campaign ### Create with a goal ```bash curl -X POST "https://www.starcovery.com/api/campaigns" \ -H "x-api-key: " \ -H "content-type: application/json" \ -d '{ "name": "Coffee", "goal": "quiet morning coffee creators who film at home" }' ``` You can include `contract`, `embargoUntil` (campaign details declassifying date), `disclosure`, and `marketInformation` on create. `contract` takes `compensationCents`, `deliverable`, `platforms`, the platforms one payment covers (`["ig"]`, `["tt"]`, or `["ig", "tt"]`), and the optional creator posting date in `creatorPostingDate`; a hired creator posts on each platform they run. `embargoUntil` needs `contract` in the same body, or the create returns 400 `invalid_campaign_terms` with the reason in `message`. `marketInformation` is `{"releaseDelayMonths": }`, the answer that decides when the campaign's name and pay per creator join the going rate, the list of campaigns and the typical pay other organizations and creators see, and that sets the platform fee. The going rate shows nothing about the organization that ran the campaign, and a campaign joins it no earlier than its declassifying date. Omit `marketInformation` to leave the question unanswered; on create, `"marketInformation": null` returns 400 `invalid_body`. Funding requires an answer. `releaseDelayMonths` takes one of these values: * `0` adds them once funding is requested, with no platform fee. * `1` to `18` holds them back that many months after the funding cycle's first funding request, for a fee of that many percent of the creator pool. A funding cycle starts at the first funding request open since the campaign last held no funds, so a full refund restarts the hold. * `null` keeps them out, for a 20% fee. To retry a create safely, send the same `idempotencyKey` (1 to 128 characters) and a complete, valid body on each attempt. A repeat with a key your organization already used returns the campaign the first request created, even when the rest of the body differs, and charges nothing. On create and update, a contract or date that fails the terms check returns 400 `invalid_campaign_terms` with the reason in `message`. ### Generate matches ```bash curl -X POST "https://www.starcovery.com/api/campaigns/{campaignId}/generate" \ -H "x-api-key: " \ -H "content-type: application/json" \ -d '{}' ``` Generation runs one creator search against the campaign goal, billed like `GET /api/search`, and stores the ranked creators on the campaign. ### Add or remove matches Add or remove individual matches with `POST /api/campaigns/{campaignId}/matches` and `DELETE /api/campaigns/{campaignId}/matches/{matchId}`. The add body carries the creator's `profileId` and `fitScore` only; the platform, handle, name, picture, and follower count of the match come from the catalog profile, and a body with any other key answers 400 `invalid_body` naming the key. Removing a match that already has a proposal delivery returns 409 `campaign_match_delivered`. ### Read, update, or export Read the campaign with matches (`GET /api/campaigns/{campaignId}`), update it (`PATCH /api/campaigns/{campaignId}`), or export the shortlist as CSV (`GET /api/campaigns/{campaignId}/export`). List the campaigns of the organization with `GET /api/campaigns`, newest update first. `?status=draft`, `?status=active`, or `?status=archived` lists only the campaigns in that status, and another value answers 400 `invalid_query`. `GET /api/campaigns` and `GET /api/campaigns/{campaignId}` carry `nextStep`, the step the web app shows next on the campaign: ```json { "id": "fund", "label": "Fund the creators who accepted", "actor": "you", "line": "2 creators accepted. Fund $600 to lock them in." } ``` For members of the organization, `GET /api/campaigns/{campaignId}` also carries `people`, each person on the campaign with their answer, funding, and signed hire. A hire lists `posts`, each live post Starcovery recorded, one per platform, with its `url`, `viewCount`, `engagementCount` (likes plus comments), and `recordedAt`. `id` is one of `pick`, `proposal`, `send`, `answers`, `fund`, `post`, and `payout`, in campaign order. `actor` names who takes the step: `you` for your organization, `starcovery`, `creators`, or `{"creator": ""}` when one funded creator has yet to post. `nextStep` is null once no step is left, because the campaign is done or archived or no creator was reached or accepted, and on a campaign another organization owns. `GET /api/campaigns/{campaignId}` also carries `currentSteps`, every step under way in campaign order, in the same shape. A step before `nextStep` can still wait: while Starcovery has not sent every proposal and a later step waits too, `nextStep` names the later step and `currentSteps` lists the `send` step before it. `currentSteps` is empty once no step is left and null on a campaign another organization owns. Update name, goal, visibility, status, contract, campaign details declassifying date (`embargoUntil`), creator posting date (`contract.creatorPostingDate`), disclosure, or `marketInformation` (`null` clears it). `contract` replaces the stored contract: send `compensationCents`, `deliverable`, and `platforms` with it, and send `creatorPostingDate` again to keep the posting date. Status takes `draft`, `archived`, or `active`; Starcovery sets `active` when the team sends the proposals, and `active` reopens an archived campaign whose proposals were sent. A campaign that is active or holds a proposal delivery cannot return to `draft`, a campaign with a send or funding request open with the Starcovery team cannot be archived, and a campaign that is not archived or was never sent cannot be set `active`; each patch returns 409 `campaign_status_locked` with `reason` `sent`, `request_open`, or `not_sent`. The contract and the disclosure lock when the team sends the proposals: while the campaign is active or holds a proposal delivery, a patch that changes or clears `contract`, or changes `disclosure`, returns 409 `contract_locked`. ```bash curl -X PATCH "https://www.starcovery.com/api/campaigns/{campaignId}" \ -H "x-api-key: " \ -H "content-type: application/json" \ -d '{ "goal": "quiet morning coffee creators who film at home" }' ``` Omit a top-level field you do not want to change. Every endpoint is in the [API reference](/docs/api) with an interactive playground. ## Send and funding requests Sending proposals and funding a campaign are staff actions. Any surface can record the request. `POST /api/campaigns/{campaignId}/send` records one open Send Proposal request and notifies the Starcovery team, who send the proposals from the staff queue. The campaign needs draft status, a contract whose creator posting date, when set, is today or a later day in UTC, a disclosure, and at least one match with 1,000 or more followers. `POST /api/campaigns/{campaignId}/fund` records one open funding request for the accepted creators not yet funded, per person, at the compensation per creator times those people plus the platform fee. The caller needs an owner or admin role in the organization, and the campaign needs a contract, market information, and at least one creator who accepted and is not yet funded (reason `no_accepted` otherwise). An archived campaign returns reason `archived`; reopen it with `{"status":"active"}` first. Both return 201 with the request row in `request`. A campaign with an open request, or one that fails a gate, returns 409 `campaign_request_denied` with the reason in `reason`. The reason `creators_changed` means a creator accepted while the funding request was prepared, and the same call is safe to repeat. A funding request from a member who is not an owner or admin returns 403 `organization_funding_forbidden`. A funding request prices the platform fee on the market information answer, so the answer locks while a funding request is open or the campaign holds funds. Then a `PATCH /api/campaigns/{campaignId}` that changes or clears `marketInformation` returns 409 `market_information_locked`. ```bash curl -X POST "https://www.starcovery.com/api/campaigns/{campaignId}/send" \ -H "x-api-key: " ``` The Starcovery team sends the proposals, invoices the organization, and pays creators. Prepaid credit packs are a different money domain and stay available. ## Visibility and cost * New campaigns are public by default. Ordinary public campaign bodies are free to read for any identified caller. * A credential bound to the organization that owns the campaign, or a browser session of one of its members, reads campaign detail at any time, including contract metadata. * A stored campaign details declassifying date (`embargoUntil`) returns 404 to identified callers outside the owning organization until that instant. * A private campaign returns 404 to identified callers outside the owning organization. Unsigned callers get 401 on every campaign endpoint. * Making a campaign private costs 1 credit: at creation, or when you change a public campaign to private. Updates to an already-private campaign do not charge again. * Generating matches runs one search, which spends the daily grant or 1 credit like `GET /api/search`. A pre-claim agent token spends 1 credit. A repeat of a search the organization already ran is free while that search is still in its search history ([Pay for API calls without a subscription](/docs/guides/credits)). ## CLI equivalents ```bash starcovery campaigns starcovery campaigns create "Coffee" --goal "quiet morning coffee creators" starcovery campaigns update --goal "quiet morning coffee creators who film at home" starcovery campaigns update --market-information 0 starcovery campaigns generate starcovery campaigns show starcovery search "coffee" --json | jq '.creators[0] | {profileId: .id, fitScore}' > creator.json starcovery campaigns add creator.json starcovery campaigns export > out.csv ``` URL: https://www.starcovery.com/docs/guides/campaigns # Check whether a creator's audience and engagement are real Read the views, engagement, posting activity, and audience countries on a Starcovery creator page, and compare them with followers and the benchmarks. To check whether a creator's audience and engagement are real in Starcovery, open the creator page and compare **Average views** and **Engagement on views** with the follower count and with the medians in [Instagram and TikTok engagement benchmarks](/reports/engagement-benchmarks). Then read the views per post, the posting activity, and the audience countries, and open the creator's profile on the platform to read the comments on recent posts. Starcovery publishes no fake-follower score and no audience-quality grade. The creator page shows the numbers in the Starcovery catalog, and you judge what they mean for your campaign. This page covers what each number on a creator page counts, how to read it, the same figures over the API, and what the steps cost. ## Steps ### Open the creator page Search from a brief on the [web](/app), or over [MCP](/docs/guides/mcp), [REST](/docs/api), or the [CLI](/docs/guides/cli). See [Search](/docs/guides/search). The results on the web show **Engagement on views** and **Average views** for each creator, and each creator name opens the creator page. To narrow the results on followers, average views, or engagement, ask the assistant, such as "only creators with engagement on views above 5%". A creator page shows one Instagram or TikTok profile. The header shows the follower count as **Followers on Instagram** or **Followers on TikTok**, and the handle under the name links to the profile on the platform. ### Compare views with followers **Average views** is the mean views of the 6 newest posts with a stored video, counting the posts that have views. The caption under **Recent posts** names how many posts it counts. Compare it with the follower count, and with the median views per post for the creator's platform and follower tier in the [benchmarks](/reports/engagement-benchmarks). An average far below that median means the creator's posts reach fewer viewers than most creators with a similar follower count. ### Compare engagement with the benchmarks **Engagement on views** is likes plus comments divided by views for each of the same posts, averaged across them. Shares do not count, and the follower count is not part of the figure. Sponsored posts and ads count like any other post. The [benchmarks](/reports/engagement-benchmarks) compute the engagement rate the same way, from each profile's 6 newest posts, and list the median by platform, follower tier, and creator country. Compare the creator's figure with the median for its platform and tier. The benchmarks cover profiles with 10,000 or more followers, so a creator with fewer followers has no tier there. ### Read the views per post **Views per post** plots the views of up to 30 of the creator's newest posts that Starcovery captured, oldest to newest, and highlights the highest bar. A post with no view count shows no bar. Bars of similar height mean each post reaches a similar number of viewers. One bar far above the rest is one post that drew far more views than the others. **Average views** counts only the 6 newest posts with a stored video, so the chart can show posts the average leaves out. ### Check the posting activity **Posting days** counts the days in the last 12 weeks, in UTC, with at least one post Starcovery captured. The **Activity** grid shows each of those days, shaded by the number of captured posts. An empty day is a day with no captured post, not a day without posts. The dates under **Recent posts** show the newest posts Starcovery stored. When those dates are weeks old or **Posting days** is low, open the profile on the platform from the handle to see what the creator posted since. ### Read the audience countries **Audience** shows the follower share by country when Starcovery has it on record: the top country in the headline, then a row for each country. Compare it with the countries where you sell. When Starcovery has no audience data for the profile, the section reads **No audience countries on record.** Ask the creator for the audience breakdown from the platform's analytics before you hire. Starcovery records no audience age or gender. ### Read the posts on the platform **Recent posts** shows the views and likes of each of the 6 newest posts with a stored video, and no comments. A post with no view count reads **No view count**. Open the profile on the platform from the handle to read the comments under recent posts. ### Hire or reveal the contact When the numbers fit your campaign, choose **Hire** to start a campaign with the creator, or choose **Reveal Contact** under **Contact** for the address. **Hire** shows for creators with 1,000 or more followers. Signed out, the contact button reads **Sign In to Reveal**. See [Pay creators and handle disclosure](/docs/guides/pay-creators) for the steps after the campaign starts. ## Check over the API `GET /api/search`, MCP `search_creators`, and `starcovery search --json` return each creator's `followerCount`, `averageViews`, and `engagementOnViews`, computed over the same 6 posts as the creator page. `engagementOnViews` is a fraction: `0.0768` is 7.68%. Each creator's `videos` lists posts with `playCount`, `likeCount`, `commentCount`, `postedAt`, `isAd`, and `isSponsored`, so an agent can compute the engagement of each post or leave sponsored posts out. ```bash curl "https://www.starcovery.com/api/search?q=fitness+creators" \ | jq '.creators[] | {username, followerCount, averageViews, engagementOnViews}' ``` The audience countries, the activity grid, and the views per post chart are on the creator page only. ## Live example [fitness creators](/search/fitness-creators) is a published search page: a ranked list of creators for the brief "fitness creators", each with platform, followers, average views, and engagement on views. Each creator name opens the creator page, such as [@gabbylgeorge](/tt/@gabbylgeorge). Read that page in the order of the steps above, and compare its **Average views** and **Engagement on views** with the TikTok figures for its follower tier in the [benchmarks](/reports/engagement-benchmarks). ## Prices A credit costs $0.05. Opening a creator page and reading its numbers spend no credits. | Step | Price | | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Open a creator page | Free | | Search within the daily grant | Free | | Search past the daily grant | 1 credit | | Search thread turn on the web, over MCP `thread_turn`, or with `starcovery thread` | 1 use for the turn, from the daily grant and then 1 credit, plus up to 3 searches and exclusions in all, each billed like a search | | Narrow a thread's creators on followers, average views, or engagement | The turn's use only, because the narrowing runs no search | | Contact reveal | 1 credit the first time your organization reveals the profile | | Private campaign | 1 credit at creation, or when a public campaign becomes private | Prepaid credit packs are on [Pricing](/pricing). See [Pay for API calls without a subscription](/docs/guides/credits) for the credit ledger. ## Frequently asked questions ### How do I know if a creator has fake followers? Starcovery publishes no fake-follower score. Compare the creator's **Average views** and **Engagement on views** with the follower count and with the medians for the platform and follower tier in the [benchmarks](/reports/engagement-benchmarks). Then read the comments under the creator's recent posts on the platform. ### Does Starcovery audit creator audiences? No. Starcovery publishes no fake-follower score and no audience-quality grade. It shows the follower count, views, engagement, posting activity, and audience countries in its catalog. ### What is a good engagement rate on Instagram or TikTok? [Instagram and TikTok engagement benchmarks](/reports/engagement-benchmarks) lists the median engagement rate and views per post by platform, follower tier, and creator country, from public profiles in the Starcovery catalog. Compare a creator with the median for its platform and follower tier. ### How does Starcovery calculate engagement? **Engagement on views** is likes plus comments divided by views for each of the creator's 6 newest posts with a stored video and views, averaged across those posts. ### Is engagement on views the same as engagement rate by followers? No. Engagement on views divides by views, not followers, so it does not match an engagement rate computed from the follower count. ### Why does a creator page show few posting days? **Posting days** counts only the posts Starcovery captured in the last 12 weeks. A day with no captured post can still be a day the creator posted. Open the profile on the platform to see the newest posts. ### Can I see where a creator's followers live? The **Audience** section shows the follower share by country when Starcovery has it on record. When it reads **No audience countries on record.**, ask the creator for the breakdown from the platform's analytics. Starcovery records no audience age or gender. ### Does checking a creator cost credits? No. Opening a creator page and reading its numbers is free. Revealing the contact address costs 1 credit the first time your organization reveals the profile. ### Can an agent check a creator's engagement? Yes. `GET /api/search`, MCP `search_creators`, and `starcovery search --json` return `averageViews`, `engagementOnViews`, and the views, likes, and comments of each post. See [Check over the API](#check-over-the-api). URL: https://www.starcovery.com/docs/guides/check-audience-and-engagement # Find a creator's email address See whether Starcovery has a creator's email address, reveal it for 1 credit, and read it on the web, in a CSV export, or over the API. To find a creator's email address in Starcovery, open the creator page and choose **Reveal Contact** under **Contact**. The first reveal of a profile costs your organization 1 credit, $0.05, and every later reveal of that profile is free. Search results and creator pages show whether Starcovery has an address before you spend a credit. A reveal that finds no address charges nothing. This page covers where the addresses come from, the steps on the web, the reveal over the API, what to do when Starcovery has no address, and what the steps cost. ## Where the addresses come from Starcovery holds each email address a creator posts in the display name, the biography, the profile link, or a caption, and each address on a public web page about the creator. Starcovery groups the Instagram and TikTok profiles it believes belong to one person, so the reveal of one profile can return an address that Starcovery found for the creator's other profile. Until your organization reveals a profile, search results, the creator page, the API, MCP, and the CLI leave the address out, also where it appears in the biography, a caption, or the profile link. ## Steps ### Find the creator Search from a brief on the [web](/app), or over [MCP](/docs/guides/mcp), [REST](/docs/api), or the [CLI](/docs/guides/cli). See [Search](/docs/guides/search). On [/app](/app), the **Creators**, **Table**, and **Map** views mark each profile with an address your organization has not revealed **Email on file**, signed in or signed out, each revealed profile **Email revealed**, and each profile without an address **No email on file**. The **Table** view shows the mark in its **Contact** column. A profile known only from another profile's link carries no mark, because the results hold only that link. Each creator name opens the creator page. ### Check the Contact card The creator page has a **Contact** card. When Starcovery has an address, the card offers **Reveal Contact** when you are signed in and **Sign In to Reveal** when you are signed out. When Starcovery has no address, the card reads "Starcovery has no address for this creator." and offers no reveal. Opening a creator page is free, signed in or signed out. ### Reveal the address A reveal needs an account and 1 prepaid credit. The daily grant of free searches does not cover it. Any member of your organization can reveal a contact, and owners and admins buy credits in [Billing settings](/home?settings=billing). Choose **Reveal Contact** in the creator page header or in the **Contact** card. The **Reveal contact** dialog shows the price, "One credit. Free after the first time.", and your organization's credit balance. Choose **Reveal Contact** to confirm. The dialog then shows the address with a button that copies it. ### Use the address The **Contact** card keeps the address, and everyone in your organization sees it on the creator page. The creator page shows one address. When Starcovery holds more than one address for the profile, the CSV export and the API list them all. To collect the addresses of many creators, select them on [/app](/app) and choose **Export CSV** in the selection bar menu. The **Contact** column holds the addresses of each profile your organization revealed, "Email on file" for a profile whose address your organization has not revealed, and "No email on file" for a profile with no address. The **Table** shows those two words, and "Email revealed" where the CSV writes addresses. ## When the reveal does not return an address The reveal dialog ends with "Nothing was charged." in each of these cases: * **No contact on file**: Starcovery has no address for the creator. * **Out of credits**: the reveal needs a credit and the balance is empty. **Buy Credits** opens Billing settings. * **Sign in again**: your session ended. When a reveal does not finish, try again. Your organization pays for a profile once, so a retry never charges twice. ## When Starcovery has no address You can still hire the creator through Starcovery. **Hire** on the creator page starts a campaign with the creator, for a profile with 1,000 or more followers. When you choose **Send Proposal**, the Starcovery team sends the proposals. See [Run a creator campaign without an agency](/docs/guides/run-a-creator-campaign). Until a creator's proposal goes out, the creator's tile on the campaign page is marked **Published email**, **Researched email**, or **No email on file**. **Published email** means the creator published the address, and **Researched email** means Starcovery has only an address it found on a web page about the creator. The **Send Proposal** confirmation counts the creators with a published address and the creators with only a researched one. To write to the creator yourself, open the profile on the platform from the handle under the creator's name. ## Reveal over the API An agent reveals one profile per call, with an access token or a Settings API key: * REST: `POST /api/creators/{profileId}/contact` * MCP: `reveal_contact` with the `profileId` from `search_creators` * CLI: `starcovery contact reveal ` ```bash curl -X POST "https://www.starcovery.com/api/creators//contact" \ -H "x-api-key: " ``` The response holds `emails`, each address Starcovery holds for the profile, and `bio`, the creator's full biography. `starcovery contact reveal` prints the addresses, and `--json` prints the response. REST answers 404 `not_found` with `reason` `no_contact` when Starcovery has no address for the profile, 404 `not_found` with no `reason` when no profile has that id, and 402 `out_of_credits` when the prepaid balance is empty. None of them charges a credit. `GET /api/search`, MCP `search_creators`, and `starcovery search --json` return `hasContact` for each creator: `true` when Starcovery has an address. After your organization reveals a profile, search results carry its addresses in `emails`. ## Live example [skincare creators](/search/skincare-creators) is a published search page: a ranked list of creators for the brief "skincare creators". Each creator name opens the creator page. Signed out, the **Contact** card of [@janethechemist](/tt/@janethechemist) shows **Sign In to Reveal**, so Starcovery has an address for that profile. The **Contact** card of [@colette.laxton](/tt/@colette.laxton) reads "Starcovery has no address for this creator." ## Prices A credit costs $0.05. | Step | Price | | -------------------------------------------------------------------- | -------- | | Open a creator page, or see whether an address is on file | Free | | Search within the daily grant | Free | | Search past the daily grant | 1 credit | | Contact reveal, the first time your organization reveals the profile | 1 credit | | A later reveal of the same profile | Free | | A reveal that finds no address | Free | | Send Proposal | Free | A reveal covers one profile. A creator's Instagram and TikTok profiles are two profiles, and the first reveal of each costs 1 credit. Prepaid credit packs are on [Pricing](/pricing). See [Pay for API calls without a subscription](/docs/guides/credits) for the credit ledger. ## Frequently asked questions ### How do I find a creator's email address? Open the creator page in Starcovery and choose **Reveal Contact** under **Contact**. The first reveal of a profile costs your organization 1 credit, $0.05. ### How much does a creator's email address cost? 1 credit, $0.05, the first time your organization reveals the profile. Later reveals of that profile are free, and a reveal that finds no address charges nothing. ### Can I see whether a creator has an email address before I pay? Yes. Search results on [/app](/app) mark each profile with an address your organization has not revealed **Email on file**, each revealed profile **Email revealed**, and each profile without an address **No email on file**, and the creator page offers a reveal only when Starcovery has an address. A profile known only from another profile's link carries no mark. Over the API, `hasContact` is `true` when Starcovery has an address. ### Where does Starcovery find creator email addresses? In the display name, the biography, the profile link, and the captions of the creator's public Instagram and TikTok profiles, and on public web pages about the creator. ### What if a creator has no email address? The creator page reads "Starcovery has no address for this creator." and nothing is charged. You can still start a campaign with **Hire**, and the Starcovery team sends the proposals. See [When Starcovery has no address](#when-starcovery-has-no-address). ### Can my team see the addresses I reveal? Yes. Everyone in your organization sees a revealed address on the creator page and in the CSV export, and nobody in your organization pays for that profile again. ### Can I export creator email addresses to a spreadsheet? Yes. On [/app](/app), select creators and choose **Export CSV**. The **Contact** column holds the addresses of each profile your organization revealed, "Email on file" for a profile whose address your organization has not revealed, and "No email on file" for a profile with no address. ### Can I get creator email addresses in bulk? Each reveal covers one profile, on the web, over REST, over MCP, and with the CLI. An agent reveals a list of creators with one call per profile. See [Reveal over the API](#reveal-over-the-api). ### Do I need a creator's email address to hire them? No. **Hire** starts a campaign with the creator, and the Starcovery team sends the proposals when you choose **Send Proposal**. Send Proposal spends no credits. URL: https://www.starcovery.com/docs/guides/find-creator-email # Pay creators and handle disclosure Fund the creators who accept your proposal, pay the Starcovery invoice, and set the disclosure statement each creator reads before they post. To pay creators in Starcovery, request funding for the creators who accepted your proposal and pay the invoice the Starcovery team emails you, and the Starcovery team pays each funded creator after they post. To handle disclosure, write a disclosure statement on the campaign before you send proposals, and each creator reads it in the proposal under **Label**. This page covers the Starcovery Payouts steps, what each step costs, and where to read the disclosure rules. Starcovery gives no legal advice. ## Steps ### Find creators Search from a brief on the [web](/app), or over [MCP](/docs/guides/mcp), [REST](/docs/api), or the [CLI](/docs/guides/cli). Save the creators you want to a campaign. See [Search](/docs/guides/search) and [Campaigns](/docs/guides/campaigns). ### Write the proposal On the campaign's **Proposal** page, set **What they post**, the platforms the one payment covers, **Pay per creator** in whole dollars, the **Creator posting date**, and the **Disclosure statement**. **What the creator sees** shows the proposal as each creator reads it. Under **More Options**, set the visibility and the **Declassifying date**. On a public campaign, signed-in visitors read the campaign details from that date. On a private campaign, the name and pay per creator join the going rate no earlier than that date, and only if your market information answer allows it. ### Send the proposal Choose **Send Proposal**. The Starcovery team sends the proposals from its staff queue. The campaign needs a contract, a disclosure statement, and at least one creator with 1,000 or more followers. A creator posting date, when set, needs to be today or a later day in UTC. Once Starcovery starts sending, the contract and the disclosure statement are locked. Visibility and the declassifying date stay editable. ### Read the answers Each creator accepts or declines. The campaign shows how many creators answered. ### Request funding On **Campaign funding**, answer the market information question: can Starcovery show this campaign's name and pay per creator in the going rate other organizations and creators see? The answer sets the platform fee, as [Prices](#prices) lists, and locks while a funding request is open or the campaign holds funds. Choose **Request Funding**. The request covers the creators who accepted and are not yet funded: the pay per creator times those creators, plus the platform fee. Only an owner or admin of the organization requests funding. ### Pay the invoice The Starcovery team emails an invoice for the requested amount. The campaign is funded once the invoice is paid. ### Creators post Each funded creator posts, by the creator posting date when one is set. Starcovery records each live post on the campaign, one per platform, with its view count and engagement count. ### Starcovery pays the creators After a funded creator posts, the Starcovery team pays that creator. The campaign shows **Paid out.** once every funded creator is paid. Over REST, set `contract`, `disclosure`, and `marketInformation` with `POST /api/campaigns` or `PATCH /api/campaigns/{campaignId}`, then call `POST /api/campaigns/{campaignId}/send` and `POST /api/campaigns/{campaignId}/fund`. See [Send and funding requests](/docs/guides/campaigns#send-and-funding-requests). ## Disclosure The disclosure statement is one text of up to 4,000 characters per campaign. A campaign without one cannot be sent. Each creator reads it in the proposal under **Label**. Over the API, set it as `"disclosure": {"statement": ""}` on create or update. In the United States, the Federal Trade Commission (FTC) publishes the Endorsement Guides. Two FTC pages explain them: * [Disclosures 101 for Social Media Influencers](https://www.ftc.gov/business-guidance/resources/disclosures-101-social-media-influencers) * [FTC's Endorsement Guides: What People Are Asking](https://www.ftc.gov/business-guidance/resources/ftcs-endorsement-guides) Starcovery gives no legal advice. Ask your counsel what your statement needs to say. ## How a creator gets paid A creator receives payouts through a payout account. The creator verifies a handle, then an owner or admin of the creator's organization chooses **Set Up Payouts** on **Payout account**. The Starcovery team sends a secure link that collects a government photo ID, a proof of address, a bank statement, and a tax form, and sends payouts only once the tax form is on file. Payout accounts are available in Canada, Switzerland, the United Kingdom, the United States, and the countries of the European Economic Area. **Payouts** lists each transfer and the amount paid to date. ## Live example [skincare creators](/search/skincare-creators) is a published search page: a ranked list of creators for the brief "skincare creators", each with platform, followers, average views, and engagement on views. Each creator name opens the creator page, such as [@janethechemist](/tt/@janethechemist). To hire from it, run the brief on the [web](/app?q=skincare+creators), save the creators you pick to a campaign, and follow the steps above. ## Prices A credit costs $0.05. Send Proposal and the funding request spend no credits. | Step | Price | | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Search within the daily grant | Free | | Search past the daily grant | 1 credit | | Search thread turn on the web, over MCP `thread_turn`, or with `starcovery thread` | 1 use for the turn, from the daily grant and then 1 credit, plus up to 3 searches and exclusions in all, each billed like a search | | Campaign generate | One search, billed like a search | | Private campaign | 1 credit at creation, or when a public campaign becomes private | | Creator pay | The pay per creator, for each funded creator | | Platform fee, market information answer **Yes** | None | | Platform fee, answer **Not for up to 18 months** | 1% to 18% of the creator pool, one percent per month held | | Platform fee, answer **No** | 20% of the creator pool | The creator pool is the pay per creator times the funded creators. For example, two creators at $300 each make a $600 pool. A 6-month hold adds a $36 fee, for an invoice of $636. Prepaid credit packs are on [Pricing](/pricing). See [Pay for API calls without a subscription](/docs/guides/credits) for the credit ledger. ## Frequently asked questions ### How do I pay a creator for a sponsored post? Request funding for the creators who accepted your proposal, then pay the invoice the Starcovery team emails you. The Starcovery team pays each funded creator after they post. ### Do I pay creators directly? No. You pay the Starcovery invoice, and the Starcovery team pays the creators. ### When does a creator get paid? After the creator posts. Starcovery records the post on the campaign, and the Starcovery team then pays the creator. ### What should a paid partnership disclosure say? Starcovery gives no legal advice. Read the FTC pages under [Disclosure](#disclosure), and ask your counsel. ### Can I change the disclosure after I send the proposal? No. The contract and the disclosure statement lock once Starcovery starts sending the proposals. ### Who in my organization can fund a campaign? An owner or admin. Another member gets **Funding needs an owner or an admin**, and over the API, 403 `organization_funding_forbidden`. ### Can I keep what I pay creators out of the going rate? Yes. Answer **No** to the market information question for a 20% platform fee, and the campaign's name and pay per creator never join the going rate. Answer **Not for up to 18 months** to hold them back that many months after your funding request, for a fee of that many percent. ### Which countries can creators get paid in? Canada, Switzerland, the United Kingdom, the United States, and the countries of the European Economic Area. URL: https://www.starcovery.com/docs/guides/pay-creators # How much to pay a creator by follower tier Starcovery publishes no rate per follower tier. Set a pay per creator from the going rate, run one campaign per tier, and pay creators after they post. Starcovery publishes no fixed rate per follower tier: each campaign sets one pay per creator in its proposal, and each creator accepts or declines it. To choose the amount, start from the going rate, the pay per creator of past Starcovery campaigns whose organizations shared it, and from its median, the typical pay, which the proposal form fills in once three campaigns have joined the going rate. The going rate does not split pay by follower tier. To pay each tier its own amount, run one campaign per tier. ## Follower tiers A tier counts the followers of one Instagram or TikTok profile. | Tier | Followers | | ----- | ------------------ | | Nano | 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 | ## Read the going rate Signed in, open [Going Rate](/proposals?view=going-rate) on the Proposals page. It lists the name and pay per creator of each campaign that joined, highest pay first, and shows the typical pay once three campaigns have joined. An entry names no organization and does not open the campaign. A campaign joins only when its organization's market information answer shares its name and pay, and no earlier than its declassifying date. The proposal form shows the same list beside **Pay per creator**. ## Set pay by tier ### Search one tier Name the tier in the brief on [/app](/app), such as "micro skincare creators in the United States". The search plan lists the tier it read under **Followers**. Over REST, MCP, or the CLI, pass the `tier` filter ([Search](/docs/guides/search)). ### Start a campaign for that tier Select the creators, choose **Add to Campaign**, then **New Campaign**. A campaign pays every creator it hires the same amount, so run one campaign for each tier you pay differently. ### Write the proposal In **Write the proposal**, set what the creators post, the platforms one payment covers, **Pay per creator** in whole dollars, and the **Disclosure statement**. The pay field starts at the typical pay when one exists. A hired creator posts on each platform the proposal names that they run. ### Send the proposal Request **Send Proposal**. The Starcovery team sends the proposals, and each creator accepts or declines the pay you set. ### Answer the market information question On **Campaign funding**, answer the market information question. The answer decides whether the campaign's name and pay per creator join the going rate, sets the platform fee, and locks while a funding request is open or the campaign holds funds: * Share them once you request funding: no platform fee. * Hold them back 1 to 18 months after the first funding request since the campaign last held no funds: 1% of the creator pool for each month. * Keep them out: 20% of the creator pool. ### Fund the creators who accepted An owner or admin of the organization requests funding for the creators who accepted: the pay per creator times those creators, plus the platform fee. The fee is added to the creator pay, not taken out of it. The Starcovery team invoices the organization. ### Starcovery pays them Starcovery pays each hired creator after it records their live post, once their payout account is enabled. A payout never exceeds the pay per creator in the proposal. [Pay creators and handle disclosure](/docs/guides/pay-creators) covers the disclosure statement, the invoice, and the creator posting date. The same steps run over the API, MCP, and the CLI: see [Campaigns](/docs/guides/campaigns). ## Live example The published search [coffee creators](/search/coffee-creators) lists each creator's followers beside the fit score. Read each creator's tier from the follower count before you add them to a campaign. ## What each step costs A credit costs $0.05. A signed-in user gets 200 free uses per rolling 24 hours, and each use past them costs 1 credit. | Step | Cost | | ----------------------------------------------------------- | -------------------------------------------------------------------------- | | Search over REST, MCP, or the CLI | 1 use | | Brief on [/app](/app), or a thread turn over MCP or the CLI | 1 use for the turn, plus 1 use for each search it runs | | Add creators to a campaign, write the proposal, send it | Free | | Make the campaign private | 1 credit | | Fund the creators who accepted | The pay per creator times the creators who accepted, plus the platform fee | | Pay the creators | Paid from the funding | Details: [Pay for API calls without a subscription](/docs/guides/credits) and [pricing](/pricing). ## Questions about creator pay ### How much should I pay a creator with 10,000 followers? Starcovery publishes no rate for Micro creators, who have 10,000 to 49,999 followers, or for any other tier. Open the [going rate](/proposals?view=going-rate) for the pay per creator of past campaigns, then set your own pay per creator in the proposal. ### Does Starcovery set creator rates? No. Your organization sets the pay per creator, and each creator accepts or declines it. ### Can one campaign pay creators different amounts? No. A campaign pays every creator it hires the same pay per creator. Run one campaign per tier to pay each tier its own amount. ### Is there a fee on top of the creator pay? It depends on the market information answer: no fee when the campaign's name and pay join the going rate once you request funding, 1% of the creator pool for each month you hold them back, up to 18 months, and 20% to keep them out. ### When does a creator get paid? After Starcovery records their live post, once their payout account is enabled. A payout never exceeds the pay per creator in the proposal. ### Does one payment cover Instagram and TikTok? Yes, when the proposal names both platforms. A hired creator posts on each platform the proposal names that they run. ### Can I see what others paid creators on Starcovery? Yes, signed in. The going rate lists the name and pay per creator of each campaign whose organization shared them, and names no organization. URL: https://www.starcovery.com/docs/guides/creator-pay # Find TikTok creators in a country for a product launch Search TikTok creators based in one country, check their followers and views, save them to a List, and start a launch campaign, with the price of each step. To find TikTok creators in a country for a product launch, write a brief on [/app](/app) that names TikTok, the country where the creators are based, and what they post, such as `TikTok creators in Germany who review running shoes`. Starcovery sets the **TikTok** and **Germany** filters from the brief, ranks the creators whose videos match it, and you save the ones you pick to a List or a campaign and send them a proposal. This page covers the countries you can filter by, the steps, a live example, the price of each step, and common questions. ## Countries The country filter means the country where the creator is based. It covers every country. Over REST, MCP, and the CLI, the `country` value is the ISO 3166-1 alpha-2 code in either letter case, read as its lowercase code, such as: | Country | `country` value | | -------------- | --------------- | | Germany | `de` | | Indonesia | `id` | | Korea | `kr` | | Mexico | `mx` | | United Kingdom | `gb` | | United States | `us` | A brief that names the creators' country in any form sets its filter: `Indonesian TikTok creators`, `TikTok creators in Indonesia`, and `TikTok creators in Jakarta` all set **Indonesia**. A city or region sets the country it lies in, so `TikTok creators in Seoul` sets **Korea**. A phrase about the audience, such as `for a US audience`, sets no country filter. When a search has no country filter, the **Country** button in the composer sets one. ## Steps ### Write the brief On [/app](/app), describe the creators in up to 200 characters: the platform, the country, and what the videos show. These briefs set TikTok and a country: * `TikTok creators in Germany who review running shoes` * `Japanese TikTok creators who film skincare routines` * `TikTok fitness creators based in the UK` Add a follower size to set a tier, such as `with 10,000 to 49,999 followers`. [Search](/docs/guides/search#parameters) lists the tiers. ### Check the filters Each filter shows as a chip in the composer: **TikTok**, and the country with its flag. Remove a chip to search again without that filter. When no country chip appears, choose **Country** beside the filter chips. It opens a searchable list of every country with its flag, and typing a name, a code, or another name finds it, so `korea` finds Korea, `uk` finds United Kingdom, and `indo` finds Indonesia. Choosing a country sets the filter and reloads the results with it. Or send a follow-up message such as `only creators based in Germany`, which narrows the creators on screen and runs no new search. ### Read the results Results open in the **Reels** view. **Creators** shows one card per creator with each handle and its followers, the engagement on views (likes plus comments per view), the average views, and the creator's country with its flag. **Table** has a column for each of these and sorts by **Followers**, **Average views**, or **Engagement on views**. Average views and engagement on views come from the creator's 6 newest posts with a stored video. Select a handle to open the creator page. ### Shortlist the creators Select the checkbox on each creator you want. The selection bar offers these actions: * **Hire These Creators** starts a campaign with the selected creators and opens it. * **Save as List** saves the creators, with the brief and filters, to a List. * **Add to Campaign** adds the creators to a campaign you already have. * **Export CSV** downloads the selected creators. Signed out, **Hire These Creators** and **Save as List** ask you to sign in. ### Turn the List into a campaign Open the List from [Lists](/lists) and choose **Add to Campaign**. Pick a campaign that still takes creators, or choose **New Campaign**. A new campaign takes its name and goal from the List's brief, and each creator on the List becomes a match. The creators stay on the List. ### Send proposals On the campaign page, choose **Write the Proposal**. Set **Pay per creator**, the **Creator posting date**, and the **Disclosure statement**, then choose **Save Proposal**, which returns you to the campaign page. Choose **Send Proposal** there and confirm. The Starcovery team sends the proposals from its staff queue. [Pay creators and handle disclosure](/docs/guides/pay-creators) covers funding and payouts. Over REST, MCP, and the CLI, pass the filters with the brief: `GET /api/search?q=running+shoe+reviews&platform=tt&country=de`, `search_creators` with `platform` and `country`, or `starcovery search "running shoe reviews" --platform tt --country de`. `POST /api/search/parse` reads the filters from a brief. ## Live example [Creators matching "fitness creators in seoul"](/search/fitness-creators-in-seoul) is a published search page. A search page is published only from a brief that ran without filters, so its 12 creators are ranked on the brief alone. On October 6, 2026, the page listed Instagram and TikTok creators, and five of its seven TikTok creators were based in Korea, such as [@.jaeho_fitness](/tt/@.jaeho_fitness) and [@kus_mingo](/tt/@kus_mingo). **Run This Search** opens the same brief on [/app](/app). To keep only TikTok creators based in Korea, write `TikTok fitness creators in Seoul` instead, and check for the **TikTok** and **Korea** chips. ## Prices A credit costs $0.05. Buy credit packs on [Pricing](/pricing). | Step | Price | | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | | A brief or a follow-up message on [/app](/app) | 1 use, plus 1 use for each search and each exclusion it runs, up to 3 in all | | A search over REST, MCP, or the CLI | 1 use | | Uses, signed out | Free for 100 uses per rolling 24 hours per IP | | Uses, signed in | Free for 200 uses per rolling 24 hours per user, then 1 credit each | | A follow-up message that only narrows by platform, country, followers, views, engagement, or verified status | 1 use, with no search | | Remove a filter chip | 1 use for the new search | | Choose a country with **Country** | 1 use for the new search | | Save as List, Add to Campaign, Hire These Creators, Export CSV | Free | | Private campaign | 1 credit at creation, or when a public campaign becomes private | | Reveal a creator's contact | 1 credit the first time your organization reveals the profile | | Send Proposal | Free | Creator pay is separate from credits. When creators accept, you fund **Pay per creator** for each of them plus a platform fee that your market information answer sets: none, 1% to 18%, or 20%. [Pay for API calls without a subscription](/docs/guides/credits) lists every credit cost, and [Pay creators and handle disclosure](/docs/guides/pay-creators#prices) lists the fee rules. ## Frequently asked questions ### How do I find TikTok creators in Korea? Write `TikTok creators in Korea` and what they post on [/app](/app), such as `TikTok creators in Korea who review sunscreen`. The **TikTok** and **Korea** chips confirm the filters. ### Can I find TikTok creators in one city? Name the city, such as `TikTok creators in Seoul`. The filter sets the country the city lies in, Korea, and covers the whole country. ### How do I find creators whose audience is in a country? Starcovery filters by where the creator is based, not where the audience is. A phrase such as `for a US audience` stays in the brief and sets no country filter. ### Which countries can I filter by? Every country. Over REST, MCP, and the CLI, pass its ISO 3166-1 alpha-2 code in either letter case, such as `id` or `ID` for Indonesia or `mx` for Mexico; the search reads it as its lowercase code. An unknown code returns 400 `invalid_query` with the message `Expected an ISO 3166-1 alpha-2 country code, such as us or id`. ### What happens when the brief sets no country? The search covers every country. Choose **Country** in the composer to set one, and the results reload with it. The **Creators** cards and the **Table** show each creator's country when Starcovery has one for the profile. ### How do I find small TikTok creators in a country? Add a follower size to the brief, such as `TikTok creators in Germany with 10,000 to 49,999 followers`. That size is the **Micro** tier, and its chip confirms the filter. ### Can I search without an account? Yes. Signed out, [/app](/app) allows 100 uses per rolling 24 hours per IP. Saving a List, starting a campaign, and revealing a contact need an account. ### Can an AI agent run this search? Yes. Over [REST](/docs/guides/search), [MCP](/docs/guides/mcp), or the [CLI](/docs/guides/cli), send the brief with `platform` set to `tt` and `country` set to the country's ISO 3166-1 alpha-2 code, in either letter case, as in [Countries](#countries). URL: https://www.starcovery.com/docs/guides/tiktok-creators-by-country # Pay for API calls without a subscription How Starcovery credits work: organization ledger, prepaid packs bought with Stripe Checkout, and agent pay-as-you-go through Stripe Checkout or machine payment. This page covers how organizations buy and spend credits, from prepaid packs to machine payment. Credits live on the organization credit ledger. Humans and agents that act inside the same organization spend the same prepaid credits. A credit costs $0.05 and buys one identified search past the daily grant or one paid product action, as the cost table below lists. There are no seats and no subscriptions. Every account is guaranteed at least one organization on first sign-in. [Organization settings](/home?settings=organization) shows the active organization's name, members, roles, and invitations. Solo users manage organization-scoped billing and credentials there. To switch the active organization, use the **Organizations** menu in the app sidebar. Owners and admins buy prepaid credits through Stripe Checkout or machine payment. Any member spends credits on search, contact reveal, and campaigns. Members without an owner or admin role cannot buy prepaid credits; Starcovery rejects the request before calling Stripe. Read the balance and identified daily search grant status: ```bash curl "https://www.starcovery.com/api/billing/state" \ -H "x-api-key: " ``` The response includes prepaid `balance`, `dailySearches` (`limit`, `remaining`, `resetAt`), and `freeGrant`. Pre-claim agent tokens return `freeGrant: "none"` and `dailySearches: null`. ## Search spend A search is one use, and a thread turn on the web, over MCP `thread_turn`, or with `starcovery thread` is one use plus one for each search and each exclusion it runs. An outside agent that calls search, List, and campaign tools directly pays only for the searches and other charged operations it runs. Unsigned callers get 100 uses per rolling 24 hours per IP. When the unsigned grant is used, unsigned search returns 402 and a thread turn streams only its out-of-allowance part. Identified callers get 200 uses per rolling 24 hours per user. Uses past that identified grant spend prepaid credits, one credit each. Pre-claim agent tokens skip the daily grant and spend prepaid credits only. 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. ## What each action costs | Action | Cost | | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | Search within the daily grant | Free | | Search past the daily grant, or with a pre-claim agent token | 1 credit | | Repeat search, while the first search is in search history (24 hours unsigned) | Free | | Search thread turn | 1 use for the turn, from the daily grant and then 1 credit, plus up to 3 searches and exclusions in all, each billed like a search | | Campaign generate | One search, billed like a search | | Shortlist enrichment | Free, with the ticket from a search | | Contact reveal | 1 credit the first time the organization reveals a profile | | Private campaign | 1 credit at creation, or when a public campaign becomes private | ## Reveal contact Creator contact addresses stay hidden until this organization reveals them. `POST /api/creators/{profileId}/contact` spends 1 prepaid credit the first time that organization reveals that profile. Later reveals return the address without charging. Search, API, MCP, CLI, and the profile UI omit the address until then. When prepaid credits are empty, contact reveal returns 402 without a Payment challenge. For an owner or admin, the 402 body includes a Stripe Checkout URL in `checkoutUrl`. Pay it, or top up in [Billing settings](/home?settings=billing), then retry. Starcovery offers the Payment challenge only on identified search. ## Prepaid packs (humans) Humans buy packs with Stripe Checkout at [Billing settings](/home?settings=billing). Larger packs include bonus credits at the same list rate. Current ladder and bonuses: [pricing](/pricing). ## Machine payments (agents) The 402 from identified search offers two ways to buy 10 credits for $0.50 (the Stripe card floor is $0.50, so a single search cannot be charged alone). Unspent credits stay on the organization credit ledger. * Stripe Checkout: the body includes a Stripe Checkout URL (`checkoutUrl`) when the caller is an organization owner or admin. One Checkout Session buys the 10 credits. Stripe credits the organization through the webhook after the session is paid. * Machine payment: when the caller is an organization owner or admin, the response includes a `WWW-Authenticate: Payment` challenge under the Machine Payments Protocol (MPP), settled with a Stripe Shared Payment Token (SPT). Settle it and retry the same request with the payment credential in `Payment-Authorization`. The challenge names that header, so `x-api-key` and `Authorization` remain free for the identity credential. No browser is needed. ### Dry-run a 402 Get a live 402 paywall body and, for an owner or admin, the Payment challenge without spending prepaid credits, warming search connections, creating a Stripe Checkout session, or settling a payment: ```bash curl -i "https://www.starcovery.com/api/search?q=coffee&force_payment=1" \ -H "x-api-key: " ``` ```http HTTP/1.1 402 Payment Required WWW-Authenticate: Payment id="", realm="", method="stripe", intent="charge", request="", description="10 Starcovery credits", expires="", header="Payment-Authorization" Cache-Control: no-store Content-Type: application/json { "authUrl": "https://www.starcovery.com/agents", "error": "out_of_credits", "machinePayment": { "available": true, "dryRun": "GET /api/search?q=test&force_payment=1 with a credential returns a live 402 with a WWW-Authenticate: Payment challenge and settles nothing.", "retry": "Settle the WWW-Authenticate Payment challenge over a Shared Payment Token, then retry GET /api/search with Payment-Authorization: Payment (see /agents)." }, "packsUrl": "https://www.starcovery.com/home?settings=billing" } ``` The sample is an owner or admin response. A member gets no `WWW-Authenticate` header, and `machinePayment` contains `available: false` with a `hint`. The header values vary per challenge; parse the `Payment` scheme instead of copying them. A real out-of-credits 402 includes `checkoutUrl` when the caller is an owner or admin. Pay that URL, then retry search with `x-api-key` only. A real 402 without `checkoutUrl` means the caller cannot start Checkout, or the request included a payment credential that did not settle. The force-payment dry-run omits it for all callers. To pay with the challenge, settle it, then retry the same search with both headers: ```bash curl -i "https://www.starcovery.com/api/search?q=coffee" \ -H "x-api-key: " \ -H "Payment-Authorization: Payment " ``` The paid 2xx response includes a `Payment-Receipt` header. An error response never includes one. Full machine payment notes are at [/agents](/agents). ### Pay from the CLI ```bash starcovery search "coffee" starcovery search "coffee" --payment ``` The CLI prints a summary line, then the `WWW-Authenticate` Payment challenge when the 402 includes one, then the 402 JSON, including `checkoutUrl` when Checkout is available. Settle the challenge, then retry with `--payment`. URL: https://www.starcovery.com/docs/guides/credits # Call a creator database over MCP Connect a Streamable HTTP MCP client to Starcovery by bearer token or OAuth to search and enrich creators, reveal contacts, run campaigns, and read credits. This page covers connecting a Model Context Protocol (MCP) client to Starcovery, the credentials it accepts, and how its tools spend credits. Starcovery exposes a Streamable HTTP MCP endpoint: ```text https://www.starcovery.com/api/mcp ``` Use an agent access token from [agent signup](/docs/authentication), a Settings API key, or OAuth when your client supports it. `initialize` and `tools/list` work without a credential. `search_creators` and `enrich_creators` also work without one. Other tools need a credential. A `tools/call` of another tool without a credential answers HTTP 401 with a `WWW-Authenticate` header whose `resource_metadata` points at `https://www.starcovery.com/.well-known/oauth-protected-resource/api/mcp`, the document an OAuth host reads to start sign-in. An unsigned `search_creators` call spends one use of the unsigned grant of 100 uses per rolling 24 hours per IP. Unsigned REST search spends the same grant. Every credential resolves to one organization for the length of the request. That organization's prepaid credits fund any credit spend. MCP OAuth access tokens and the `/api/auth/oauth2/userinfo` response include an `organization_id` claim. Authorization embeds the organization that is active at consent time, or the caller's first organization when none is active. An issued token stays bound to that organization. Changing the session's active organization does not move an existing token. To bind a different organization, authorize again and replace the token. When you authorize, pick the organization under **Give access to** on the consent screen, or switch the active organization from the **Organizations** menu in the app sidebar first. An OAuth access token lasts one hour, and it stops working sooner when the browser session that approved it signs out or expires. A host that holds the **Stay signed in** permission (`offline_access`) gets a new access token from its refresh token, which survives the sign-out, and keeps working. A host without that permission stops working until you authorize it again. With a credential, each new search that `search_creators`, `generate_campaign_matches`, or a `thread_turn` runs spends one use of the identified grant of 200 uses per rolling 24 hours per user, then 1 prepaid credit from the organization credit ledger. Each `thread_turn` also costs 1 use of its own before it runs, so a turn costs 1 plus each search and each exclusion it runs. A turn that fails gets its use back, and so does a turn whose website read or brief draft times out, fails with a search or model error, finds no pages to read, or finds no description of a product or audience. A pre-claim agent token skips the daily grant and spends prepaid credits only. A repeat of a brief and filters that the organization already searched spends nothing while that search stays in its search history. A `thread_turn` that leaves a kind of creator out of the creators on screen runs the exclusion judge over them and spends like a new search, and nothing when no creators are on screen. Narrowing them on followers, average views, engagement, platform, country, or verified status spends nothing. When a search needs a credit and the organization has no prepaid credits left, each tool reports it: * `search_creators` and `generate_campaign_matches` return an `out of credits` error. * `thread_turn` reports the condition in `exhausted`, with empty `creators`, when no search or exclusion in the turn has succeeded or when the first search for a new brief's creators needs a credit. * `thread_turn` answers with the brief, filters, reply, and creators built from the steps that succeeded when a search or exclusion in the turn already succeeded, and `exhausted` is null. See [Pay for API calls without a subscription](/docs/guides/credits). Over MCP you can inspect the current identity and credit source, search creators from a brief, enrich the shortlist (niche, celebrity, evidence, signal), reveal a contact address, run a search thread turn, intersect two creator lists, save, list, read, and delete Lists, list, read, create, update, delete, and export campaigns, generate, add, and remove matches, list and delete campaign attachments, request a proposal send or campaign funding, read the credit balance, and list, create, and revoke API keys. Search, generate, enrich, and thread turns hold the call open until the result, and the api ends a request at 800 seconds. The web, REST, and the CLI run the same operations, except Lists, which only the web and MCP have, and campaign attachments, which the CLI does not have. An agent access token or an OAuth access token cannot manage API keys. ## Search threads and Lists `thread_turn` runs one turn of a search thread and answers the settled brief, its filters, the operations the turn ran, the reply, and the creators of the thread result set in `creators`, with a `shortlistId` for `enrich_creators`. `creatorCount` counts the whole set, and `creators` holds at most the 50 best fit of them, fewer when the result would pass 140,000 characters, so it fits an AI client's tool result limit. The reply, statement, and error are cut to 4,000 characters, and `operations` lists at most the first 20. Omit `threadId` to open a thread; the `threadId` in the result is the durable handle to pass back on the next turn. 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, and the turn changes none of them. A refinement returns the set it built; the first brief runs one search for its creators, billed like `search_creators`. The thread stores the set, so `GET /api/threads/{threadId}/results` reads it again for free. When the read of the thread's creators fails after the turn ran, `thread_turn` answers a tool error with two texts: `internal`, then the turn without `creators` and `shortlistId`, its `threadId` included. MCP cannot stream a tool result, so the call is blocking and sends `notifications/progress` when the host passes a `progressToken`. `intersect_lists` keeps the creators that appear in both lists, in the order of the left list, and stores nothing. `save_list` saves a set of creators as a List for the organization, with the brief and filters of the search that produced it. `list_lists` lists the organization's Lists, `get_list` reads one List with its saved creators, and `delete_list` deletes one List; campaigns keep the creators added from it. These tools need a credential. `list_campaigns` and `get_campaign` return `nextStep` on each campaign of the organization: the step the web app shows next, with its `id`, its `label`, the `actor` who takes it (`you` for the organization, `starcovery`, `creators`, or one creator by name), and the `line` that says what it waits on. It is null once no step is left and on a campaign another organization owns. `get_campaign` also returns `currentSteps`, every step under way in campaign order, in the same shape, because a step before `nextStep` can still wait, such as proposals Starcovery has not sent yet. `add_campaign_match`, `add_campaign_matches`, `create_campaign`, and `save_list` take each creator as a pick of `profileId` and `fitScore` only, the same body `POST /api/campaigns/{campaignId}/matches` takes. The catalog profile supplies the platform, handle, name, picture, and follower count, so a pick carries nothing else: a creator with any other key, such as the `platform` or `username` that `search_creators` and `get_list` return, fails the call with a validation error naming the key. `add_campaign_matches` adds several creators to a campaign in one call and answers how many it added and how many were already on the campaign. `create_campaign` takes the same optional `creators` and adds them as matches of the new campaign. Pick `profileId` (the creator id) and `fitScore` from each creator of a `search_creators` or `get_list` result before you call these tools. `intersect_lists` is the exception: it echoes the creators it is given and stores nothing, so it takes and returns the full saved creator shape that `get_list` returns. To pass a `search_creators` result to `intersect_lists`, map each creator first: `profileId` is the creator id, and `fitScore`, `followerCount`, `name`, `platform`, `profileImageUrl`, and `username` carry over. ## Get a credential ```bash npx starcovery auth register ``` That runs the auth.md signup protocol and saves an agent access token as `apiKey` in `~/.config/starcovery/config.json`. The CLI prints the config path and the claim endpoint, never the raw token. It then installs the [host skill](/agents/skill) with `bunx skills` when `bun` is on PATH, otherwise `npx -y skills`, for Cursor, Claude Code, and Codex. An agent access token lasts 24 hours. When it expires, the CLI exchanges the saved assertion for a new token, which retires the old one, so a copy pasted into an MCP host stops working within a day. For a long-lived MCP host, use OAuth, or have a human mint a Settings API key in [**Settings** > **API Keys**](/home?settings=api-keys). Claude Desktop does not load filesystem skills. Download [skill.zip](https://www.starcovery.com/agents/skill.zip) and upload it at **Customize** > **Skills** with code execution on. MCP is a separate connector below. ## Claude Code ```bash claude mcp add --transport http starcovery https://www.starcovery.com/api/mcp ``` Open `/mcp` in Claude Code and complete browser sign-in. To use a Settings API key instead: ```bash claude mcp add --transport http starcovery https://www.starcovery.com/api/mcp --header "Authorization: Bearer " ``` ## Claude and Claude Desktop Claude on the web and Claude Desktop connect to Starcovery as a custom connector. On a Free, Pro, or Max plan, open **Customize** > **Connectors**, select **Add custom connector**, and enter these values: * Name: `Starcovery` * Remote MCP server URL: `https://www.starcovery.com/api/mcp` * **Authentication**: **Sign in now** * **OAuth client**: **Register automatically** If the dialog shows only a name, a URL, and **Advanced settings**, leave the OAuth client ID and secret empty. Sign in to Starcovery when Claude opens the sign-in page, and pick the organization under **Give access to**. **Register automatically** registers Claude's OAuth client through dynamic client registration. Starcovery does not advertise client ID metadata documents, which **Use Claude's published identity** needs. **Sign in now** makes every tool call run as your organization, `search_creators` included. The Free plan holds one custom connector. On a Team or Enterprise plan, an Owner adds the connector under **Organization settings** > **Connectors** (**Add**, then **Custom**, then **Web**) with the same values, and each member selects **Connect** on it under **Customize** > **Connectors**. To use a Settings API key instead of OAuth, choose **No sign-in** under **Authentication** and add a request header named `authorization` with the value `Bearer `. Claude shows **Request headers** only to the organizations in its beta. ## Cursor Cursor connects with a Settings API key in a header. Add Starcovery to `~/.cursor/mcp.json`: ```json { "mcpServers": { "starcovery": { "url": "https://www.starcovery.com/api/mcp", "headers": { "Authorization": "Bearer " } } } } ``` Cursor's OAuth sign-in does not connect to Starcovery. Cursor's client registration includes the callback `cursor://anysphere.cursor-mcp/oauth/callback`, and the registration endpoint refuses that callback with 400 `invalid_redirect_uri` before sign-in starts. ## Codex ```bash codex mcp add starcovery --url https://www.starcovery.com/api/mcp ``` Codex detects OAuth on the endpoint, registers its own client, and opens browser sign-in. Sign in to Starcovery and pick the organization under **Give access to**. To sign in again later, run `codex mcp login starcovery`. To use a Settings API key instead, store it in an environment variable of the shell that runs Codex, and pass the variable's name to `--bearer-token-env-var`: ```bash export STARCOVERY_API_KEY= codex mcp add starcovery --url https://www.starcovery.com/api/mcp --bearer-token-env-var STARCOVERY_API_KEY ``` Codex sends the variable's value as `Authorization: Bearer ` and skips OAuth. Both commands write a `[mcp_servers.starcovery]` entry to `~/.codex/config.toml`. ## Other HTTP MCP hosts Add a custom MCP server: * URL: `https://www.starcovery.com/api/mcp` * Auth: `Bearer `, or OAuth when the host offers it A host that registers its own OAuth client posts to the `registration_endpoint` in `/.well-known/oauth-authorization-server`. A host whose callback is a loopback address, such as `http://127.0.0.1:/callback` or `http://localhost:/callback`, registers with `"application_type": "native"`. A registration without `application_type` is a web client, which needs an `https` callback on a host that is not loopback; any other callback answers 400 `invalid_redirect_uri`. > Some hosts only accept a query parameter: `https://www.starcovery.com/api/mcp?api_key=`. This is a last resort. Keys in URLs can leak through server logs, browser history, and the Referer header. Prefer Bearer or OAuth. ## Example prompt Ask your agent to read these docs, install the [host skill](/agents/skill) if needed, register if needed, then search: ```text Find 15 nano creators who film quiet morning coffee at home on Instagram or TikTok. Reveal a contact only when you need to write them. Save the shortlist to a campaign named Coffee. ``` ## Web app and API reference questions ### Do I need the web? No. MCP, REST, and the CLI cover search, thread turns, shortlist enrichment, contact reveal, campaigns, and credits. MCP also intersects, saves, reads, and deletes Lists. API key management needs a browser session or a Settings API key; an agent access token or an OAuth access token gets 403. Humans use the web for account settings and credit packs. Search, generate, enrich, and thread turns hold the connection open until the result is ready. ### Where is the API described? [openapi.json](https://www.starcovery.com/openapi.json) documents the REST surface, and the [API reference](/docs/api) renders it with a playground. MCP describes itself: call `tools/list` on the endpoint, or read the [server card](https://www.starcovery.com/api/mcp/server-card). URL: https://www.starcovery.com/docs/guides/mcp # Add Starcovery to ChatGPT Add Starcovery to ChatGPT as a custom MCP server, sign in to Starcovery, and find Instagram and TikTok creators from a brief in a ChatGPT chat. This page covers adding Starcovery to ChatGPT on the web, so you can find Instagram and TikTok creators from a brief in a ChatGPT chat. You add Starcovery once as a custom MCP server, sign in to Starcovery, and then pick Starcovery in any chat. Starcovery is not listed in the ChatGPT plugin directory. You add it by its address: ```text https://www.starcovery.com/api/mcp ``` ## Before you start You need ChatGPT on the web, in a plan that can run Starcovery searches. OpenAI's [Developer mode and MCP apps in ChatGPT](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt) lists full MCP support for these plans: * **Business**: only a workspace owner or admin can add a custom MCP server. * **Enterprise** and **Edu**: owners and admins, and members an admin grants developer access. On **Pro**, OpenAI allows read and fetch tools only. A Starcovery search counts as a write action in ChatGPT, because it spends a search use, so on Pro, ChatGPT can connect Starcovery but cannot run a search. The **Free** and **Plus** plans are not on OpenAI's list, so they cannot add Starcovery. You also need a Starcovery account. ChatGPT asks you to sign in to Starcovery when you connect it. ## Add Starcovery ### Open Add custom MCP server In ChatGPT, open **Plugins** in the left sidebar. Select **Add**, then **Add custom MCP server**. ![The Add menu on the ChatGPT Plugins page, with Add custom MCP server at the bottom](/images/guides/chatgpt/add-menu.webp) ### Enter the Starcovery address 1. Under **Name**, enter `Starcovery`. 2. Under **Connection**, keep **Server URL** and paste `https://www.starcovery.com/api/mcp`. 3. Under **Authentication**, keep **OAuth**. 4. Read the risk warning and check **I understand and want to continue**. 5. Select **Create as a plugin**. ![The Add custom MCP server form filled in with the name Starcovery, the Starcovery address, and OAuth](/images/guides/chatgpt/add-form.webp) ### Sign in to Starcovery Install the plugin when ChatGPT offers it. When ChatGPT connects Starcovery, it shows **Connect Starcovery**. Select **Continue to Starcovery**. ![The Connect Starcovery dialog in ChatGPT, with the Continue to Starcovery button](/images/guides/chatgpt/connect.webp) Sign in to Starcovery with your email or with Google. On the consent screen, pick the organization whose credits ChatGPT spends under **Give access to**, then allow access. ![The Sign in to Starcovery screen that ChatGPT opens](/images/guides/chatgpt/sign-in.webp) ### Check the tools Open the Starcovery plugin and select the **Starcovery** app to see its tools. ChatGPT sorts them into **Write** and **Read**. Searches and changes to Lists and campaigns are under **Write**. ![The Starcovery app in ChatGPT, with 18 write tools and 10 read tools](/images/guides/chatgpt/tools.webp) ## Find creators in a chat ### Pick Starcovery and describe the creators Start a new chat, type `@`, and pick **Starcovery**. Then describe the creators you want: ```text Find 10 US fitness creators on Instagram with 50k to 200k followers ``` ![A ChatGPT chat with Starcovery picked and a brief for 10 US fitness creators on Instagram](/images/guides/chatgpt/brief.webp) ### Approve the search if ChatGPT asks A Starcovery search is a write action, and ChatGPT can ask you to approve a write action before it runs. When ChatGPT asks, check the brief and approve it. ### Read the creators ChatGPT lists the creators Starcovery found, with their followers and what they post. Ask for changes in the same chat, such as fewer followers or another country. ![ChatGPT's answer with the first US fitness creators on Instagram that Starcovery found, with their followers, specialty, and average video views](/images/guides/chatgpt/answer.webp) Each search spends one use of your daily grant, then one prepaid credit of the organization you picked. See [Pay for API calls without a subscription](/docs/guides/credits). To give your workspace the plugin, an owner or admin selects **Publish to workspace** on the Starcovery plugin settings page. For other assistants and the full tool list, see [Call a creator database over MCP](/docs/guides/mcp). URL: https://www.starcovery.com/docs/guides/chatgpt # Add Starcovery to Microsoft 365 Copilot Install the Starcovery agent in your Microsoft 365 organization so people can search creators, save Lists, reveal contacts, and run campaigns from Copilot. This page covers installing the Starcovery agent in Microsoft 365 Copilot for one organization. The agent connects Copilot to the Starcovery [MCP server](/docs/guides/mcp), so people in your organization can find Instagram and TikTok creators from a brief, save Lists, reveal contacts, and run campaigns from Copilot. A Microsoft 365 admin installs the agent for the organization. The agent is not listed in the Microsoft agent store. ## Before you start You need: * A Microsoft 365 admin account that can upload a custom agent in the [Microsoft 365 admin center](https://admin.microsoft.com/). * [Node.js](https://nodejs.org/) on your computer, to run the Microsoft 365 Agents Toolkit. Each person who uses the agent needs a Microsoft 365 Copilot license, or Microsoft 365 Copilot Chat through an eligible Microsoft 365 license. See [Plan licensing and cost for Microsoft 365 Copilot extensibility](https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/cost-considerations). Each person also needs a Starcovery account. Copilot asks each person to sign in to Starcovery. The agent spends the credits of the Starcovery organization that the person picks under **Give access to** on the Starcovery consent screen. ## Download the agent Download [starcovery-copilot.zip](https://www.starcovery.com/agents/microsoft-365-copilot.zip) and unzip it. The `starcovery-copilot` folder holds the agent files and `m365agents.yml`, the project file that the toolkit reads. ## Register the agent with your organization Copilot signs people in to Starcovery through a sign-in registration that Microsoft stores for your organization. The Microsoft 365 Agents Toolkit creates the registration and builds the agent package. 1. Open a terminal in the `starcovery-copilot` folder. 2. Sign in with your Microsoft 365 admin account: ```bash npx -y @microsoft/m365agentstoolkit-cli auth login m365 ``` 3. Register the agent and build its package: ```bash npx -y @microsoft/m365agentstoolkit-cli provision --env dev ``` The `provision` command creates the app in the Teams Developer Portal, registers Copilot as a Starcovery sign-in client, stores that registration for your organization, checks the package with Microsoft's validation rules, and saves the package as `appPackage/build/starcovery.zip`. It writes the app ID and the registration ID to `env/.env.dev`. ## Upload the agent 1. In the [Microsoft 365 admin center](https://admin.microsoft.com/), open Copilot controls and select **Agents** > **Upload custom agent**. 2. Select **Choose File**, then select `appPackage/build/starcovery.zip` in the `starcovery-copilot` folder. 3. Check the agent's name, icon, and host products, then select **Next**. 4. Select who gets the agent, then select **Next**. To try the agent before other people get it, select **Just me**. 5. Review the agent's permissions and capabilities, then select **Next**. 6. Select **Finish deployment**. Microsoft describes these steps in [Upload Microsoft Copilot custom agents](https://learn.microsoft.com/en-us/microsoft-365/copilot/agent-essentials/agent-lifecycle/agent-upload-agents). ## Use the agent Open Microsoft 365 Copilot and pick the Starcovery agent. Pick a conversation starter, or describe the creators you want: ```text Find 15 nano creators who film quiet morning coffee at home on Instagram or TikTok. ``` When Copilot asks you to sign in to Starcovery, sign in and pick the organization under **Give access to**. The agent's instructions tell Copilot to ask you before it reveals a contact, sends or funds a campaign, or deletes anything. Searches, contact reveals, and the other tools spend credits as they do over MCP. See [Pay for API calls without a subscription](/docs/guides/credits). URL: https://www.starcovery.com/docs/guides/microsoft-365-copilot # CLI Use the Starcovery CLI to sign in, check the active identity, search creators, run thread turns, and manage campaigns, credits, API keys, and contact reveal. This guide covers signing in to the Starcovery CLI, searching creators, running thread turns, and managing campaigns, credits, API keys, contact reveal, and payments. The CLI is the [starcovery npm package](https://www.npmjs.com/package/starcovery). `npx starcovery` and `bunx starcovery` run it with no install. The CLI needs Node.js 24 or newer. Bare `auth`, `campaigns`, `credits`, `keys`, and `whoami` only read. A change takes an explicit verb, such as `create` or `delete`. ## Search without an account ```bash npx starcovery search "slow morning coffee" ``` Unsigned search is free up to 100 uses per rolling 24 hours per IP, and an identified caller gets 200. A pre-claim agent token from `starcovery auth register` skips the daily grant and spends prepaid credits only. A search is one use, and a `starcovery thread` turn is one use plus one for each search and each exclusion it runs. JSON output includes each creator's link-in-bio URL as `externalUrl` when the search result has one. Table and CSV put that URL in the `Link` column. The CLI waits up to 300 seconds for search, generate, and the creators read after a thread turn. Enrich and the thread turn itself wait until the api answers, and the api ends a request at 800 seconds. Each call holds the connection open until the result is ready. ## Thread turns ```bash starcovery thread "creators who post home coffee" starcovery thread "only on Instagram" --thread ``` One command opens a search thread and runs one turn, or continues the thread named with `--thread`. 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, and the turn changes none of them. When the turn ends, the CLI writes the result to stdout: the thread id, the status, the settled brief, its filters, and the reply, followed by the creators of the thread result set as `starcovery search` prints them. The progress lines of the turn follow on stderr. JSON matches the turn result plus `threadId`, `creators`, and `ticket`. Pass the thread id back with `--thread` to continue the conversation. A refinement shows the set it built; the first brief runs one search for its creators, billed like `starcovery search`, and the thread stores the set, so reading it again is free. The command needs a credential. The Model Context Protocol (MCP) tool `thread_turn` and `POST /api/threads/{threadId}/turns` run the same loop. ## Agent signup For browser OAuth: ```bash npx starcovery auth login ``` The command opens the browser, stores a refreshable OAuth credential, and binds it to the organization active during consent. For agentic signup without a browser: ```bash npx starcovery auth register ``` This follows the [auth.md protocol](/docs/authentication), exchanges the assertion for an agent access token, writes `~/.config/starcovery/config.json`, and installs the [host skill](/agents/skill) with `bunx skills` when `bun` is on PATH, otherwise `npx -y skills`. To hand the registered identity to a person, run this command with their email address: ```bash npx starcovery auth claim ``` Starcovery mails a claim link to that address. The person opens it, signs in with Google, and selects **Claim This Account**. The next CLI command then saves the claimed credential. If that command stops with a claim notice, run it again. The identity keeps its credits, campaigns, and history. You can also pass credentials per call: ```bash export STARCOVERY_ACCESS_TOKEN= starcovery search "running shoes" --access-token ``` A person can mint a Settings API key in [**Settings** > **API Keys**](/home?settings=api-keys) and save it with this command: ```bash starcovery auth set ``` Inspect the active credential and credit routing: ```bash starcovery whoami ``` The output identifies the credential, user, and organization. It also shows whether the next search uses the user's free grant or the organization's prepaid credits. ## Campaign and account commands These commands manage campaigns, contact reveal, enrichment, thread turns, credits, and Settings API keys: ```bash starcovery campaigns starcovery campaigns create "Coffee" --goal "quiet morning coffee creators" starcovery campaigns generate starcovery campaigns show starcovery search "coffee" --json | jq '.creators[0] | {profileId: .id, fitScore}' > creator.json starcovery campaigns add creator.json starcovery campaigns export > out.csv starcovery campaigns update --market-information 0 starcovery campaigns send starcovery campaigns fund starcovery contact reveal starcovery search "coffee" --enrich --json starcovery search "coffee" --json > search.json starcovery enrich search.json --json starcovery thread "creators who post home coffee" starcovery credits starcovery keys ``` Campaigns, contact reveal, credits, and thread turns need an access token or a Settings API key. `keys` needs a Settings API key; an agent access token gets 403. `campaigns fund` requests funding for the accepted creators not yet funded, per person. The caller needs an owner or admin role in the organization; another member gets 403 `organization_funding_forbidden`. The campaign needs a contract, a market information answer, and at least one creator who accepted. Set the answer with `--market-information` on `campaigns create` or `campaigns update`. The answer decides when the campaign's name and pay per creator join the going rate, the list of campaigns and the typical pay other organizations and creators see, no earlier than the declassifying date, and takes one of these values: * `0` adds them once funding is requested, with no platform fee. * `1` to `18` holds them back that many months after the funding cycle's first funding request, for a fee of that many percent of the creator pool. A funding cycle starts at the first funding request open since the campaign last held no funds, so a full refund restarts the hold. * `never` keeps them out, for a 20% fee. The answer locks while a funding request is open or the campaign holds funds. Then a `campaigns update` that changes the answer fails with 409 `market_information_locked`. Search results omit contact addresses until `starcovery contact reveal`. That command spends 1 prepaid credit the first time this organization reveals that profile. Later reveals do not charge again. After the reveal, a search with the same organization's credential lists every address of that profile in the Contact column and in `emails`. Plain `starcovery search --json` output matches `GET /api/search` (`creators`, `query`, and the enrichment `ticket`). `starcovery search --enrich --json` adds an `analysis` object with each creator's niche, celebrity, evidence, and signal. `starcovery enrich --json` prints the same shape for a saved `starcovery search --json` result. ## When a search asks for payment Identified search past the daily grant spends prepaid credits and returns 402 when the organization has no prepaid credits left. The CLI writes a summary line to stderr, with the `checkoutUrl` when the body has one, then the Payment challenge when the 402 includes one, then the 402 JSON body, and exits with code 1. Pay in one of two ways. Either way, one payment adds 10 prepaid credits for $0.50 to the organization credit ledger. * Checkout: an owner or admin of the organization gets `checkoutUrl` in the body. Pay that Stripe Checkout session, then run the same search again with an access token or API key. * Machine payment: for an owner or admin of the organization, the 402 includes a `WWW-Authenticate: Payment` challenge. The challenge uses the Machine Payments Protocol (MPP) over a Stripe Shared Payment Token (SPT). Settle it, then run the same search again with the payment credential in `--payment` or `STARCOVERY_PAYMENT`. ```bash starcovery search "running shoes" --payment ``` The CLI sends the payment credential in the `Payment-Authorization` header and keeps the access token or API key on `Authorization` or `x-api-key`. The credits go to that identity's organization, so without an access token or API key the CLI refuses the payment credential before any request. Only `search` takes `--payment`; a thread turn settles no payment. A payment credential that is unreadable or minted for a different caller or organization settles nothing, and the search answers with a new 402 challenge. To see the 402 without paying, call `GET /api/search?q=test&force_payment=1` with an access token or API key. The response contains the 402 body and, for an owner or admin, the challenge, creates no Checkout session, and settles nothing. For more about payments, see [Pay for API calls without a subscription](/docs/guides/credits) and the [agent protocol](/agents). ## CLI and web parity ### Does the CLI expose a smaller API than the web? Yes, in places. Search, thread turns, shortlist enrichment, contact reveal, campaigns, credits, and keys run the same operations as the web and MCP. Lists, campaign attachments, and handle claims have no CLI command. Account checkout and the claim ceremony stay on the web. Search, generate, enrich, and thread turns return their result in the same call. URL: https://www.starcovery.com/docs/guides/cli # API versioning How Starcovery versions REST and MCP, and how deprecation is signaled. Starcovery REST and MCP are version **1**. Send the optional `API-Version` header with value `1`. Every response carries `API-Version: 1`, the version served, whatever version the request sent; the server does not refuse another value, because no other version exists. Paths stay under `/api` without a `/v1` prefix. A breaking change increments `API-Version`. Starcovery does not keep a parallel old path after a break. ## Deprecation Responses send no `Deprecation` (RFC 9745) or `Sunset` (RFC 8594) header. The OpenAPI description at [/openapi.json](/openapi.json) is the live contract, and a removed operation is deleted from it. ## Rate limits Unsigned callers get 100 uses per rolling 24 hours per client IP, and identified callers get 200 per user, then prepaid credits. A `GET /api/search` request is one use, and a thread turn is one use plus one for each search and each exclusion it runs. Brief parse allows 50 requests per 60 seconds per client IP. The search quota name is `search`. The brief parse quota name is `parse`. A pre-claim agent token spends prepaid credits only, so its search responses send no `search` quota headers. Every response sends `API-Version`. Search and brief parse responses send `RateLimit-Limit` and `RateLimit-Policy`, a 400 included, except a search 401 for a credential that does not verify. An operation whose security in [/openapi.json](/openapi.json) lists the `apiKey` scheme sends both under the quota name `api-key` once the key verifies, and on a search response that quota replaces `search`. Brief parse, `GET /api/health`, and every other operation whose security does not list the scheme do not read the key and send no `api-key` quota. The MCP endpoint sends the `api-key` quota the same way once a key verifies. When the limiter reports remaining, responses also send `RateLimit`, `RateLimit-Remaining`, and `RateLimit-Reset`. Every 429 sends `Retry-After` and the body `{"error": "rate_limited"}`, on REST and MCP alike. A 429 from the `api-key`, `parse`, or `site` (website read) quota also sends that quota's `RateLimit` headers with no uses remaining, in place of the `api-key` quota. Enrichment and thread turns count against the brief parse quota, so their 429 sends it too. A search 402 sends `Retry-After` when the daily grant is used. Success responses do not send `Retry-After`. ## Test call Unsigned search is the live test call, on the same host as production calls: ```bash curl "https://www.starcovery.com/api/search?q=slow+morning+coffee" ``` URL: https://www.starcovery.com/docs/guides/versioning # Add creator search to an AI agent From one brief, find, hire, cross-post, measure, and pay out Instagram and TikTok creators from the web, MCP, REST, or CLI. AI creator search means describing the creator you need and getting real people ranked for the brief. It does not mean generating fake user-generated content (UGC). Starcovery matches a brief to Instagram and TikTok creators, backs every match with sample videos, and runs hire, measure, and payout on one platform. Start on the [web](/), or wire search into an agent through [Model Context Protocol (MCP)](/docs/guides/mcp), [REST](/docs/api), or the [CLI](/docs/guides/cli). ## What it is You describe the audience, the vibe, and the campaign goal. You get ranked creators with a fit score and sample videos you can watch. Today that means Instagram and TikTok. Starcovery does not generate creative content. Creators make the work. Starcovery finds the right people for the brief, hires them, and pays them out. ## Who it is for * AI builders and agents who want creator search from MCP, CLI, or API. Start at [Authentication](/docs/authentication). * Agencies that need Lists and campaigns without buying an enterprise seat first. * Indie marketers who want to try free, then buy packs when they need more searches than the free allowance includes. Web, MCP, API, and CLI run the same search, thread turns, shortlist enrichment, campaigns, and credit balance operations. Lists are on the web and MCP only. Campaign attachments are on the web and the API, and MCP lists and deletes them. Search, generate, enrich, and thread turns return their result in the same call, with no job id. ## How a search works 1. Describe the creator you want. 2. Get ranked creators with proof clips you can check. 3. Save creators to a campaign, or keep going from the [web](/). 4. Keep searching. Signed in, you get 200 uses per rolling 24 hours, then prepaid credits. A search is one use, and an assistant turn is one use plus one for each search and each exclusion it runs. 5. Match, hire, measure, and pay out on one platform. ## Why teams pick Starcovery * Real creators with real audiences. * Search at [/app](/app) with no card. Buy prepaid packs when you need more searches than the free allowance includes. * Affordable search. No agency seat required to start. * Agent-ready surfaces: [MCP](/docs/guides/mcp), [CLI](/docs/guides/cli), and [OpenAPI](https://www.starcovery.com/openapi.json). Named comparisons live on [Starcovery vs Modash](/vs/modash), [Starcovery vs HypeAuditor](/vs/hypeauditor), [Starcovery vs Collabstr](/vs/collabstr), [Starcovery vs GRIN](/vs/grin), [Starcovery vs Heepsy](/vs/heepsy), and [Starcovery vs Influencity](/vs/influencity). Searches people repeat on Starcovery are published with the creators each one found, on [Creator searches](/search). ## Start in the surface you already use | Surface | Entry | | ------------ | ---------------------------------------------------- | | Web | [www.starcovery.com](/) | | Agent signup | [Authentication](/docs/authentication) | | MCP | [Call a creator database over MCP](/docs/guides/mcp) | | CLI | [CLI](/docs/guides/cli) | | REST | [API playground](/docs/api) | | Pricing | [www.starcovery.com/pricing](/pricing) | ## Questions about AI creator search ### What is AI creator search? Discovery of real Instagram and TikTok creators, ranked for your brief, with proof clips. Not AI-generated UGC. ### Does Starcovery generate creator content? No. Creators make the content. Starcovery matches and helps you hire. ### Which platforms does Starcovery cover? Instagram and TikTok. ### Can I try it without a card? Yes. Search at [/app](/app) with no account and no card, 100 uses per rolling 24 hours, where a search is one use and an assistant turn is one use plus one for each search and each exclusion it runs. Signed in, you get 200 per rolling 24 hours, then prepaid credits. ### Can agents use Starcovery? Yes. Read [Authentication](/docs/authentication) for MCP, API, CLI, and auth.md registration. ### How is this different from an influencer database? You describe what you need in natural language and get ranked creators with proof clips, instead of only filtering rows in a static database UI. ### How much does it cost after the free tier? See [pricing](/pricing). Uniform credit pricing. Buy packs when you need more searches than the free allowance includes. URL: https://www.starcovery.com/docs/guides/ai-creator-search # How to build and share a creator shortlist Save the creators you pick from a search as a List, share it with your team or a client, and add it to a campaign, with the cost of each step. To build a creator shortlist in Starcovery, describe the creators you need at [/app](/app), select the ones you want, and press **Save as List**. To share it, invite your teammates to your organization, where every member opens the organization's Lists, or add the List to a campaign and send the campaign link to anyone signed in to Starcovery. This page covers each step, what a List keeps, what each person you share with sees, and what each step costs. ## Build the shortlist ### Describe the creators Open [/app](/app) and write the brief, such as "skincare creators in Korea who film morning routines". The results show ranked Instagram and TikTok creators with their videos. ### Narrow the results Write what to change in the chat, such as "only Instagram" or "under 50,000 followers". Narrowing on followers, average views, engagement, platform, country, or verified status runs no new search. Leaving out a kind of creator, such as "no brand accounts", runs an exclusion. ### Select the creators Check the box on each creator you want. The selection bar shows how many creators you selected. ### Save as a List Press **Save as List**. The List takes its name from the brief, and a second List from the same brief gets a number. **Open List** opens it. Signed out, **Save as List** asks you to sign in first and keeps your search and your selection. On [/app](/app), in **Agent** mode, you can also ask the assistant to save the creators on screen as a List. Its reply links **Open List**. ## What a List keeps A List belongs to your organization. It keeps: * The brief and the filters of the search that produced it. * Each creator you saved, with their name, handle, platform, follower count, and fit score. * The search it was saved from. **Open Search** on the List page reopens it. Every List of the organization is at [/lists](/lists). On the List page, **Add to Campaign** adds the creators to a campaign and keeps them on the List, and the actions menu holds **Rename List** and **Delete List**. ## Share the shortlist ### With your team Every member of your organization opens its Lists at [/lists](/lists), whatever their role, and can rename or delete a List. Owners and admins add people with **Invite Member** in [Organization settings](/home?settings=organization). The invitation mail is valid for 48 hours, and the invited person joins as an admin or a member. A List has no public link. A signed-in person outside your organization who opens the address of a List sees a page that does not exist. ### As a spreadsheet On [/app](/app), select creators and choose **Export CSV** in the selection bar menu. The file holds each creator's name, handles, contact, country, followers, engagement on views, average views, niche, evidence, and signal. The niche, evidence, and signal columns hold what the Table shows once Starcovery has read the creator's posts. The contact column holds the addresses once your organization reveals them, and "Email on file" or "No email on file" before that. A campaign exports its creators too: **Export CSV** in the campaign actions menu downloads each creator's rank, handle, name, platform, followers, and fit score. ### With a client outside your organization 1. On the List page, press **Add to Campaign**. Pick a campaign that still takes creators, or press **New Campaign**. 2. On the campaign page, open the campaign actions menu and choose **Share**, then **Copy Link**. 3. Send the link. A new campaign is public. Anyone signed in to Starcovery can open a public campaign, from its declassifying date when one is set. They see the campaign name, goal, status, and each creator with their follower count, and they can change nothing. A person who is signed out signs in first. A private campaign opens only for people in your organization. ## See a shortlist from a real search [Creators matching "skincare creators"](/search/skincare-creators) is a published search page: up to 12 creators from a saved search for that brief, ranked for it. Each card opens the creator's page. **Run This Search** opens the same brief at [/app](/app), where you can select creators and save them as a List. More published searches: [coffee creators](/search/coffee-creators) and [fitness creators](/search/fitness-creators). ## What each step costs Signed in, you get 200 uses per rolling 24 hours. Past them, each use spends 1 credit, and a credit costs $0.05. | Step | Cost | | ------------------------------------------------ | ------------------------------------------------------------------ | | Send a brief at /app | 1 use for the message, plus 1 for each search or exclusion it runs | | Send a chat message that narrows the results | 1 use, plus 1 for each search or exclusion it runs | | Save as List, rename, or delete a List | Free | | Invite a member | Free, with no seats | | Export CSV | Free | | Add to Campaign, including a new public campaign | Free | | Make a campaign private | 1 credit | | Reveal a creator's contact | 1 credit the first time your organization reveals that profile | A brief at [/app](/app) usually runs 1 search and costs 2 uses. A brief that names a platform, a country, or a follower tier, such as the brief in the first step, runs 2 searches while at least 2 of your daily uses remain, and costs 3 uses: the results load once without those filters and once with them. [Credits and payments](/docs/guides/credits) covers the full cost table, and [pricing](/pricing) lists the credit packs. ## Build a List from an agent Over [Model Context Protocol (MCP)](/docs/guides/mcp), `save_list` saves creators from a search as a List with the search's brief and filters, `list_lists` and `get_list` read the organization's Lists, and `delete_list` deletes one. The REST API and the CLI have no List endpoint or command. ## Questions about creator shortlists ### How do I share a creator list with my team? Invite your teammates to your organization with **Invite Member** in [Organization settings](/home?settings=organization). Every member opens the organization's Lists at [/lists](/lists). ### Can I send a shortlist to a client who has no Starcovery account? Send the CSV from **Export CSV**. A campaign link opens only for a person signed in to Starcovery. ### Can I export a creator shortlist to Google Sheets or Excel? Yes. **Export CSV** on [/app](/app) or on a campaign downloads a CSV file, which Google Sheets and Excel open. ### Does saving a shortlist cost anything? No. Saving, renaming, and deleting a List is free. The searches that find the creators spend uses, and past the 200 uses, credits. ### How do I get the email addresses of the creators on my list? Open the creator's page and press **Reveal Contact**. The first reveal of a profile costs your organization 1 credit, and later reveals of that profile are free. The address then appears in the contact column of **Export CSV** on [/app](/app). ### What is the difference between a List and a campaign? A List is a saved set of creators with the search that produced it. A campaign holds a goal and a shortlist that Starcovery sends proposals to, hires from, and pays out. **Add to Campaign** adds the creators of a List to a campaign. URL: https://www.starcovery.com/docs/guides/creator-shortlist # Report feedback Send a bug or feature request from the web or from POST /api/feedback. Every report reaches the Starcovery board at Quackback. Signed-in humans report from the Starcovery web. Agents report through `POST /api/feedback`. Starcovery MCP and the CLI do not create feedback posts. ## On the web Sign in, then open **Support** in the app sidebar. That control opens a dialog on the site. Starcovery sends the report to Quackback with the page path, whether you were signed in, and the Starcovery environment that sent it. It sends no account identifier. ## Report through the REST API `POST /api/feedback` creates the same post. It accepts an unsigned call, a Starcovery API key, or a bearer token. The operation is `feedback.submitFeedback` in [/openapi.json](/openapi.json), which contains the length limits. The body has `title`, `body`, and `path`, a site-relative path. A created post answers `201` with `{"ok": true}`. ```bash curl -X POST "https://www.starcovery.com/api/feedback" \ -H "Content-Type: application/json" \ -d '{"title":"Search results stay blank after submit","body":"The list stays empty after the brief is sent.","path":"/home"}' ``` URL: https://www.starcovery.com/docs/guides/feedback