Skip to main content
Orbit meters work against the credit balance for your API key’s account or organization. Open Billing to see your balance, usage, and available credit packages.

​
Credit Rates

You can also read the current rates from the pricing catalog. This endpoint does not require an API key.

​
Cached Profiles

Search is billed in blocks of cached profiles returned, using the block size and rate in the pricing catalog. Incomplete blocks round up. A search that returns no cached profiles has no cached-profile search charge. Candidate Discovery results are excluded from the cached-result count. They use the discovery or generation rate described below, not an additional cached-profile search charge. Polling does not bill the same cached results again.

​
Discovery and Profile Generation

Candidate Discovery charges for each unique profile returned in a search. If discovery returns an existing profile without generating it, the discovery rate applies. If the same operation generates a partial or full profile, the corresponding generation rate replaces the discovery charge for that profile; the charges are not added together. Polling the same search does not charge again for profiles already returned. A profile’s tier can rise while the operation runs, and Orbit charges only the difference up to the higher rate: a profile charged the discovery rate that later reaches partial depth costs the partial rate in total. When two results resolve to the same person, that person carries one charge, and Orbit refunds the duplicate charge to your balance. Generation uses the requested profile level. Partial generation and full generation have separate rates. A full-generation operation includes its intermediate partial profile; it is not a partial charge plus a full charge. A later explicit upgrade to full generation is a new full-generation operation. The same generation rates apply whether you request profiles through Search, Enrich, an integration, or an upgrade of an existing profile. A profile already at the requested depth does not incur a new generation charge unless you request regeneration.

​
Reservations

A reservation is a hold on credits. Orbit holds credits when an operation starts, charges each result as it is delivered, and releases the rest when the operation reaches a terminal status. A POST /v3/search holds the sum of:
  • the cached-profile search rate for the requested limit, in blocks;
  • with candidate_discovery: true, the generation rate for the requested profile_depth, once for each profile candidate_discovery_limit allows;
  • with signals.face_source, the face search rate.
The hold is a ceiling for the whole search, and most searches settle well below it. A search that finds fewer people than its limits allow, or whose results already sit at the requested depth, releases the difference when it ends. Orbit raises the hold once when cached results turn out to need generation to reach profile_depth. When the balance covers the funded work and falls short of those upgrades, the funded work runs to completion, and each cached result awaiting an upgrade ends failed with the code developer_api_credits_insufficient and the reason insufficient_upgrade_credits. Add credits and start a new request to build those profiles. Charges belong to the results Orbit delivers. The share of the hold for a result that ends failed returns to your balance when the operation ends. An Enrich request holds the generation rate for its operation; regenerate holds the full rate. In a batch, each child places its own hold, and a child whose hold exceeds the balance ends failed with developer_api_credits_insufficient while the other children continue. A profile already at the requested depth holds nothing.

​
Operations in Progress

Held credits leave your available balance when an operation starts, and the unused part returns when it ends. Your available balance therefore sets how many operations can be in progress together: a balance ten times the size of one request’s hold supports ten of those requests at once. A full-depth build stays open for many minutes, so size the balance for your peak number of operations in progress. Read heldCredits on each billing object to see what an open operation still holds. A request whose hold is larger than the available balance returns 402, and the same request succeeds once open operations settle or after a top-up.

​
Population Searches

A population search returns everyone at a company or everyone who attended a school. Its price is quoted before it starts as one total, from the profile-read and profile-generation rates at the profile_depth you chose; a full population costs more than a partial one. Orbit reserves the quoted credits when the search starts, settles them as the work completes, and releases the unused credits.

​
Profile Reads

An explicit profile read, such as GET /v3/enrich/{profile_id} or MCP get_profile, uses the profile-read rate. It returns the current stored profile and can schedule a refresh when that data is stale. With include_profile: true, Search embeds each readable result’s profile with its identity and contact fields and generated sections. Search charges cover the profiles that Search embeds, and a separate read after Search is a billable profile read.

​
Reading Your Charge

Search, Enrich, and profile-read responses carry a billing object with the credits held and spent for that operation, when the request opened a billing operation.
The numbers show the arithmetic only; rates come from the pricing table. Poll until status is settled to read the operation’s final consumedCredits. The final figure is the full charge for the request. An Enrich request that returns 202 always carries billing, and its final consumedCredits is 0 when the profile was already at the requested depth. An Enrich request that Orbit answers with 200 from the stored profile omits billing. In a batch, each child carries its own billing, and the batch charge is the sum of its children. A face search is a POST /v3/search with signals.face_source. It costs the face search rate in the credit rates, charged once Orbit searches the web for the face, plus the normal discovery or generation rate for each person it returns. A face that Orbit cannot read releases the face search rate. Detecting faces and searching the face index are free.

​
Watchers

Each completed watcher run uses the watcher-run rate. A run that produces an update also uses the watcher-update rate. Review charge_amount in watcher runs. A watcher pauses when its balance is insufficient; top up before resuming it.

​
Insufficient Credits

Billable work requires an available credit balance. Handle 402 developer_api_credits_insufficient by inspecting requiredCredits and remainingCredits, then topping up before retrying. Validation, authentication, and rate-limit rejections do not consume credits. An accepted asynchronous request can finish with only some results. Inspect the returned status and per-result failures rather than assuming every requested profile completed.

​
Retries and Polling

Use the same Idempotency-Key and request body when retrying a logical request. Persist the search or enrichment ID returned by the API and poll that resource instead of starting the work again. Do not reuse a key for different work. Status polling is covered by the accepted operation and does not repeat charges for work already billed. See the endpoint reference for profile-read options and the response fields returned by a status request.

​
Rate Limits

Credits and rate limits are independent. A request can return 429 even when credits are available, or 402 while its rate-limit bucket still has capacity.