Credits and payments
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 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:
curl "https://www.starcovery.com/api/billing/state" \
-H "x-api-key: <access_token>"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 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. A brief that contains exclude, excluding, except, or without, or asks for real people, indie creators, or individual creators, calls a model, so its repeat spends like a new search.
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, except a brief that calls a model, which spends like a new search |
| Search thread turn | 1 use for the turn, from the daily grant and then 1 credit, plus up to 3 searches, 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, then retry. Starcovery offers the Payment challenge only on identified search.
Prepaid packs (humans)
Humans buy packs with Stripe Checkout at Billing settings. Larger packs include bonus credits at the same list rate. Current ladder and bonuses: 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: Paymentchallenge 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 inPayment-Authorization. The challenge names that header, sox-api-keyandAuthorizationremain 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:
curl -i "https://www.starcovery.com/api/search?q=coffee&force_payment=1" \
-H "x-api-key: <access_token>"HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="<id>", realm="<realm>", method="stripe", intent="charge", request="<request>", description="10 Starcovery credits", expires="<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 <credential> (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:
curl -i "https://www.starcovery.com/api/search?q=coffee" \
-H "x-api-key: <access_token>" \
-H "Payment-Authorization: Payment <credential>"The paid 2xx response includes a Payment-Receipt header. An error response never includes one. Full machine payment notes are at /agents.
Pay from the CLI
starcovery search "coffee"
starcovery search "coffee" --payment <credential>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.