Pricing and billing
Credits and what a call costs, per call or per result, the price ceiling and holds, quotes, what is free, plans and what a credit costs, data retention by plan, buying credits, auto top-up and spend alerts, your balance, expiry and the three 402 errors.
Last updated
On this page
You pay for calls in credits. Every successful call takes its price, in whole credits, from your workspace's balance. A credit costs $0.005 on Pay as you go and less on a plan, and most calls cost 1 or 2 credits. This page explains how a call's price is set, what is free, and how buying credits works.
Credits
Credits are the one unit you spend. They are whole numbers, so a balance, a charge and a key's spend limit are always exact.
- What a call costs is set per API, in credits, from what the API costs to serve. It is the same on every plan.
- What a credit costs depends on your plan: $0.005 on Pay as you go, and less on Builder, Pro, Scale and Enterprise, most of all for the credits a plan includes (plans below).
- Where credits come from: credits you buy, credits included with a plan every month, and 25 welcome credits for a new account's first workspace.
What a call costs
Each API is priced in one of two ways:
| Model | You pay | Used for | Shown as |
|---|---|---|---|
Per call (per_call) | A fixed number of credits for each successful call | Most APIs: lookups, validations, single records and many searches | 2 credits per call |
Per result (per_result) | Credits for each result returned, rounded up to whole credits per call, and at least price.minCredits | Some list and search APIs | 3.24 credits per result |
A successful call always costs at least 1 credit. Each API page shows two figures:
- Usual price (
fromCredits, andpriceinGET /v1/apis/{sku}): what a call normally costs. - Ceiling (
maxCredits): when a call has to be retried elsewhere at a higher price, it costs that price, up to this figure. When the two figures are equal, a call always costs the same.
The most one particular call can cost depends on its input, for per-result APIs on limit above all. A quote states it as maxCredits, and a call is never charged more than that. To set a cap of your own, send maxCredits with the call. credits in the response always tells you what the call actually cost.
Per-result prices
A per-result API multiplies its price per result by the results returned and rounds up to whole credits. facebook.search_posts, for example, has price.creditsPerResult 3.2375 (3.24 on its page) and price.minCredits 4:
| Posts returned | Results × price | Charged (credits) |
|---|---|---|
| 1 | 3.2375 | 4 (the minimum) |
| 3 | 9.7125 | 10 |
| 12 | 38.85 | 39 |
Holds, then settlement
Before a call runs, we hold the most it could cost from your balance, so concurrent calls can never overdraw it. When the answer comes back, we charge what the call actually cost and the rest of the hold comes back at once. If every attempt fails, the whole hold comes back.
The hold is the quote's maxCredits for your input, or your own maxCredits cap if that is lower. For a per-result API it covers the largest result your input allows, usually the limit field:
| Step | Example: facebook.search_posts with limit 20 |
|---|---|
| Quote | credits 65 (20 posts at the usual price), maxCredits 127 |
| Held before the call | 127 credits |
| Posts returned | 12 |
Charged (credits) | 12 × 3.2375 = 38.85, rounded up: 39 credits |
| Back at once | 88 credits |
Your balance has to cover the hold, not only the expected price. With 100 credits left, the call above answers 402 insufficient_balance even though it would have cost less; lower limit or buy credits. Key spend limits work on the same held amount.
Quotes
POST /v1/quote/{sku} takes the same body as a run and returns the price without calling any upstream or charging anything:
| Field | Meaning |
|---|---|
credits | The expected price of this call: the best available price for this input. |
maxCredits | The most it can cost: what a run would hold (the unused part comes back at once). A call is never charged more. |
unit | request (per call) or result (per result). |
inputValid | Always true on a 200: the input passed validation. |
Quotes validate the input and routing controls exactly like a run, so they are also a free way to check a request. Prices in a quote reflect the routing controls you send.
What is free
You are charged only for an answer. Everything else costs nothing:
- errors: invalid input, authentication, access and balance errors,
all_sources_failed, timeouts, rate limits, - failed attempts that were retried automatically,
- discovery (
GET /v1/apis,GET /v1/catalog) and quotes, - polling a running request and re-reading a stored result (
GET /v1/requests/{id},GET /v1/results/{id}), - idempotent replays: a repeated
Idempotency-Keyreturns the stored result without a new charge, - balance, usage and key management, feedback and bug reports.
Misses
A call that finds nothing (output.found: false: the profile does not exist, the account is private, the search matched nothing) is a successful answer, and it is free unless the API's reference page says misses are billed. On those few APIs a miss costs the credits of one call or one result, and credits always shows what was charged.
Plans and what a credit costs
A plan doesn't change what a call costs: every API costs the same credits on every plan. A plan's fee comes back as credits every month at a discount, and extra credits you buy on a plan cost more than those but less than Pay as you go.
| Plan | Fee a month (monthly · yearly) | Credits included a month | Included credits per 1,000 (monthly · yearly) | Extra credits per 1,000 |
|---|---|---|---|---|
| Pay as you go | None | None | None | $5.00 |
| Builder | $49 · $41 | 14,000 | $3.50 · $3.00 | $4.50 |
| Pro | $149 · $123 | 50,000 | $3.00 · $2.50 | $4.00 |
| Scale | $699 · $581 | 279,600 | $2.50 · $2.10 | $3.50 |
| Enterprise | From $1,999 · from $1,665 | From 1,000,000 | From $2.00 · from $1.70 | Per contract |
- A plan's fee comes back as credits every month: Builder's $49 is 14,000 credits a month ($3.50 per 1,000), and billed yearly its $41 a month brings the same 14,000 ($3.00 per 1,000).
- Compared with Pay as you go, included credits on Builder, Pro and Scale cost 30%, 40% and 50% less billed monthly, and 40%, 50% and 58% less billed yearly.
- Extra credits cost the plan's extra-credit price, the same billed monthly or yearly: 10%, 20% and 30% less than Pay as you go on Builder, Pro and Scale. So the plan that covers your usage is the best value.
- Yearly billing is paid upfront and works out to about two months free.
- Enterprise prices, included credits and terms are set per contract; the figures above are where they start.
Plans are chosen in Dashboard → Settings → Billing → Plans while they are on sale. creditPriceUsd in GET /v1/balance is what buying a credit costs your workspace right now.
Data retention
A plan also sets how long we keep your call results and webhook event bodies:
| Plan | Call results | Webhook event bodies |
|---|---|---|
| Pay as you go | 24 hours | Until delivered |
| Builder | 7 days | 7 days |
| Pro | 30 days | 30 days |
| Scale | 90 days | 90 days |
| Enterprise | 90 days, or as agreed | 90 days, or as agreed |
- A stored result can be re-read for free (Durable requests); a kept event body can be redelivered (Webhooks).
- The period is fixed when the call or the event is made. Moving to another plan changes it for new data only: it never shortens what is already kept.
- Logs are kept on every plan: your request history, monitor runs, and webhook deliveries with their attempt logs.
Buying credits
Buy credits in Dashboard → Settings → Billing. Choose a pack of 2,500, 10,000, 25,000 or 100,000 credits, or any amount from 1,000 to 1,000,000 in steps of 100. They cost Pay as you go's price or your plan's extra-credit price: 10,000 credits are $50.00 on Pay as you go and $40.00 on Pro.
Payment runs through Stripe Checkout. The credits are added as soon as Stripe confirms the payment, usually within seconds, and the purchase appears in the ledger and in GET /v1/billing/orders. Card details go to Stripe; we never see the card number.
Auto top-up
Auto top-up buys credits for you before you run out. Turn it on in Dashboard → Settings → Billing, choose a balance to top up at (1,000 credits unless you change it) and how many credits each top-up buys (10,000 unless you change it), and save a card on Stripe's page. Saving the card charges nothing.
- We check your balance every minute. When it is below your threshold, we charge the saved card for the credits, at your price for credits (Pay as you go's, or your plan's extra-credit price). Set the threshold to cover at least a minute of your calls.
- One top-up runs at a time, and at most 10 run in any 24 hours, so a runaway loop can't keep charging your card. If that limit is reached, we email you and it starts again on its own.
- If the card is declined, or your bank asks to confirm the payment, auto top-up turns off and we email the workspace's owner, admins and billing members. Save a card again, or turn it back on, to restart it.
- Top-ups appear in your purchases as auto top-ups, and in the ledger. Low-balance emails stop while auto top-up is on.
- We keep the card's brand, last four digits and expiry so you can see which card is charged; the card itself stays with Stripe. Removing it on Billing turns auto top-up off.
Spend alerts
Spend alerts email the workspace's owner, admins and billing members as auto top-up spend passes parts of a monthly budget you set, for example 50%, 80% and 100% of $100. Each part sends one email a month, and a month is a calendar month in UTC. Changing the budget starts the month's alerts over. Alerts are notifications only: passing the budget never stops your calls or auto top-up.
Your balance
A balance can hold three kinds of credits, spent in this order:
| Credits | Come from | Rules |
|---|---|---|
Welcome credits (promoCredits) | 25 credits for a new account's first workspace, and any promotions | Spent first. They can expire: promoExpiresAt says when. |
Included credits (includedCredits) | Your plan, every month | Spent next. Each month's credits roll over for 3 months, then expire. |
Bought credits (paidCredits) | The credits you buy | Spent last. They never expire. |
credits is the total you can spend now. Read it in the dashboard or with GET /v1/balance:
curl -sS "https://api.primaryapi.com/v1/balance" -H "Authorization: Bearer $PRIMARYAPI_VIEW_KEY"{
"credits": 2525,
"paidCredits": 2500,
"promoCredits": 25,
"promoExpiresAt": "2027-02-07T14:05:09.120Z",
"includedCredits": 0,
"includedExpiry": null,
"creditPriceUsd": 0.005
}Reading the balance needs a key with full or view access (or the dashboard); run keys cannot see billing data. We email the account owner when the balance runs low (at most once a day while you are using the API), when it runs out, and if keys are paused.
Every movement of credits is in the ledger, GET /v1/billing/ledger: purchases, welcome and included credits and their expiry, each call's charge, holds that came back, and adjustments, each with the balance after it. See Balance and billing for every field.
Expiry and refunds
- Bought credits never expire.
- Included credits you don't spend roll over for 3 months, then expire.
- Welcome credits can expire;
promoExpiresAtsays when. - Credits are non-refundable and have no cash value.
- A failed call is never charged in the first place, so there is nothing to claim for errors.
- A workspace that still holds credits can't be deleted (
409 workspace_has_balance): use the credits first.
Questions about a purchase: write to [email protected] from the account's email address.
Payment errors
Three errors use HTTP 402. None of them is charged, and each tells you what to do:
| Code | What happened | What to do |
|---|---|---|
insufficient_balance | Your credits can't cover the call's hold, or the workspace's keys are paused after 48 hours without credits. | Buy credits. Paused keys resume on their own once you do. Lowering limit lowers the hold. |
key_limit_reached | This key's own spend limit for the current window can't cover the call's hold. The workspace may still have credits. details carries limitCredits, spentCredits (this window), requiredCredits, limitInterval and windowResetsAt. | Wait for windowResetsAt, raise the key's limit, or use another key. |
trial_cap_reached | An agent trial key's remaining trial credits can't cover the call's hold. | Send upgrade.claimUrl from the error body to a human, who approves the key and its spend limit. A smaller limit may still fit the remaining credits. |
{
"code": "trial_cap_reached",
"error": "this trial key has used its free allowance — ask a human to approve continued use at the link in upgrade.claimUrl",
"requestId": "req_01JBXQ8N0R2T4W6Y8A0C2E4G6J",
"upgrade": {
"claimUrl": "https://primaryapi.com/dashboard/authorize?claim=3f1c…",
"authorizationServer": "https://api.primaryapi.com",
"scope": "run balance:read"
}
}Where to see what you spent
creditson every response.GET /v1/usage: credits spent today, this week and this month, per API, per day and per member.GET /v1/requests: every call with its status, credits and latency.- Per key:
spentInWindowCreditsandspentTotalCreditson the key, andGET /v1/api-keys/{id}/usage.