Credits and billing

Spore meters in credits. The Free plan gives 50 credits when you sign up; 500 more when an Owner verifies a payment method (no charge). Starter and Pro include monthly grants, and Enterprise is custom. Top-ups buy more at the plan's rate. Reads are free, while state changes are free unless they buy data or compute.

The Free plan's credits

The 50 sign-up credits arrive when the Organization is created, once per person: an Organization whose founder already received them for another Organization gets none, and its Free card offers only the 500. The 500 more arrive once the Organization's Owner presses Verify a payment method on the Free plan card in Dashboard → Organization → Billing and saves a payment method on the checkout page that opens. Nothing is charged. When the Owner is back on the Billing page, the balance moves to 550 by itself, without a reload; only the Owner sees the action, and it goes away once the 500 credits are granted.

A payment method counts as verified when checkout confirms it for later use and it carries a stable identity that tells it apart from every other payment method, as a card or a SEPA Direct Debit account does. The 500 credits are granted once per Organization, once per Owner, and once per payment method. The Billing page says why when a verification earns nothing, and the Organization keeps its sign-up credits:

• the payment method already earned the 500 credits for another Organization;
• the payment method has no stable identity, so the same one could fund any number of Organizations;
• the Owner already earned them for another Organization; or
• the Organization has had a subscription or redeemed a coupon.

After either of the first two, the Owner can verify another payment method. After either of the last two, no payment method can earn them, so the action goes away and the reason stays in its place.

Per-call prices

The replay identity is the canonical request hash over filter, sortBy, sortOrder, and sampleSize (with defaults applied), not filterHash alone. Changing the sort or sample size evaluates a distinct request and can charge again; an unexpired matching searchResultId is the replay receipt.

Every operation page in the API reference states its own price in prose, and the agent guide states the same price for the same operation. Both are generated from the same constants the runtime charges, so a price cannot be documented at one number and billed at another.

What is free, and why

Free is not generosity, it is a design constraint: an agent that must pay to find out what it can afford will make worse decisions.

• GET /api/v1/wallet — the balance, plus lifetime purchased, granted and used, and under keyBounds the mandate this key is actually operating under, including how much of its rolling budget is left.
• GET /api/v1/wallet/transactions — the ledger, refunds included.
• GET /api/v1/catalog?section=… — the tool, filter, knowledge, and NACE vocabularies.
• Creating, editing, deleting, and reading live Segments; recording your own knowledge; cancelling a launch; and every other read.

Failed work is refunded

Credits are charged by the child workflow's first durable step, and what a child keeps follows from its outcome. A child that failed — Spore's fault — is refunded in full. A child that couldn't look or was cancelled is refunded the part no provider work consumed. Found and nothing found are answers and stay charged in full. The exact rules are in Enrichment lifecycle.

Variable prices are quoted

Some operations have no fixed price because it depends on how many companies they touch — POST /api/v1/search, POST /api/v1/search/{searchId}/unlock, POST /api/v1/companies/legal-entity, and POST /api/v1/enrich. The Legal entity read and the search's population door both charge one credit for each Legal entity the organization has not yet been granted; that grant is permanent. These operations are quoted or bounded before they run:

• dryRun: true on any of them returns the quote, writes nothing, and charges nothing. It skips the organization-balance gate, so an agent still receives the quote even when it exceeds the current balance; maxCredits and the key's spend bounds remain enforced. A search's quote is its worst case, max(5, sampleSize): the exact charge depends on the matches, and the count is part of what a search sells, so a free dry run reads nothing from the registry and the search charges the quote or less. A Legal entity read's quote is what it charges, less what it cannot deliver: a Legal entity the registry no longer carries, or one unlocked between the quote and the read.
• An unlock that would overrun your maxCredits, your plan's Company allowance, or your balance is refused whole, before anything is minted.

Their reference pages say "Variable price, quoted per request" rather than a number, because a zero base is a floor and not a charge.

Reading the ledger

curl "https://www.spore.ee/api/v1/wallet/transactions?limit=50" \
  -H "Authorization: Bearer $SPORE_API_KEY"

Rows come newest first, cursor-paged. Each row carries the apiKeyId that spent it (null for dashboard sessions and system spend) and what the charge referred to. Add ?apiKeyId= to narrow to one principal.

When you run out

A call the organization cannot afford is a 402 with error: "insufficient_credits". A call your key cannot afford — because of its own bounds rather than the balance — is a 402 naming the bound: request_cap_exceeded or key_budget_exhausted. A variable-cost call whose declared ceiling is too low is a 402 with error: "max_credits_exceeded" and the exact requiredCredits and caller-supplied maxCredits:

{
	"error": "max_credits_exceeded",
	"message": "The launch quote exceeds maxCredits.",
	"requiredCredits": 12,
	"maxCredits": 5
}

Read requiredCredits, then retry the same operation with maxCredits at least that high (and with a fresh Idempotency-Key if the prior request was refused). For search, the ceiling must cover the worst-case sample charge max(5, sampleSize); for the population door and enrich, it must cover the quote returned by the operation. The exact bodies are in Authentication and keys; the full status set is in Conventions.