Billing & Credits

Fiber runs on a credit-based model. You hold a credit balance; chargeable operations consume credits per result/item; many supporting operations are free. Pricing is designed to be transparent and predictable, with free previews/estimates and authoritative post-call reconciliation.

All plans, subscriptions, and top-ups are priced in US dollars. For help with payment problems, see Payment troubleshooting.

How credits work

• Per-item pricing. Chargeable operations bill per result or per item found (e.g., per company returned, per email revealed), not per API call. A search that returns nothing costs nothing.

• chargeInfo is authoritative. Every chargeable response includes output.chargeInfo (or chargeInfo): the real amount charged. Always surface it verbatim rather than estimating from published rates. Its method tells you how the call was billed:

  method	Meaning
  charged-now	Charged on this call (creditsCharged)
  charged-for-async-process	Charged up front for a background job (creditsCharged); undelivered items are refunded when it finishes
  charging-later	Billed after the job runs
  credits-refunded	This call returned credits (creditsRefunded)
  free	No charge

  When your balance is 500 credits or less, chargeInfo also carries a lowCreditAlert with your availableCredits and a getMoreCreditsUrl.

• Check balance (free): GET /v1/get-org-credits?apiKey=xxx.

• Estimate before charging: where one exists (e.g., the audience enrichment cost estimate), call it and confirm before committing.

• Some operations are volume-tiered. The per-unit price for an operation can step down once you pass a threshold within a period, so a large job's average cost may land below the published rate. chargeInfo reflects what you actually paid.

• Costs can be fractional. Credits are tracked at sub-credit precision, so an operation may cost 1.5 credits rather than rounding up to 2.

Managing billing over the API

Six endpoints cover balance, purchase, and limits:

A credit balance check returns one entry per subscription (max, used, available, and usagePeriodResetsOn), plus creditsPerOperation carrying your organization's actual per-operation pricing, which supersedes the representative table below.

A rate-limit lookup returns the effective limit for every endpoint (method, path, max, windowSeconds), so a client can read live values instead of hardcoding them. isCustom: true marks a limit we've raised or tuned for your organization.

Rate limits on these endpoints: credit balance 120/minute, rate-limit lookup 20/minute, auto top-up read and configure 10/minute, credit top-up 2/minute. Billing, API-key, and webhook management keep working at a zero balance, so you can always top up and fix settings.

Representative per-item costs

A few common prices are below. Every operation's default price, what it bills per, and how volume pricing works are on Pricing by operation.

Some products bill per operation/request instead of per item (for example, market-intelligence lookups like hotels/flights/finance and social media APIs bill per call). The response's chargeInfo tells you exactly what a given call cost.

Free operations

Many operations cost nothing:

• Account/observability: check credits (get-org-credits), rate limits, health check, reference enums.
• Audience setup: create audience, set search params, estimate enrichment cost, poll status.
• Tracker: adding entities, reading signals, managing lists, firing dummy signals, previewing signal payloads.

Some paid operations bill only on a hit, so a miss costs nothing: reverse email, reverse phone, and hashed email lookups, premium phone, work email from a name and company, and every contact-reveal channel that comes back empty.

Search counts aren't free, but they're cheap: 1 credit per count, whatever the match total. Size a search with a count before you pull results — see counting before you spend.

The count and estimate operations:

Running out of credits

A chargeable call your balance can't cover returns HTTP 402:

{ "error": "INSUFFICIENT_CREDITS", "message": "Insufficient credits. Please top up your account." }

A 402 with "error": "PLAN_EXPIRED" means your billing period ended, even if credits remain; renew the plan or ask us for an extension. Handle both in production code so long-running jobs can pause and resume rather than crash, and watch for lowCreditAlert on earlier responses to top up before you hit zero.

A 403 with "error": "API_KEY_CREDIT_LIMIT_REACHED" is different: the org still has credits, but the key you called with hit its own credit limit. See What happens at the limit.

Top-ups

Top-ups add credits to your balance immediately, charged to your card on file. No plan change, no interruption to your current cycle. Buy them with a credit top-up (POST /v1/buy-credits).

• Purchase bounds: a top-up is between 100 and 1,000,000 credits. Charging a saved card needs at least 1,000.
• Price depends on your plan: $20 per 1,000 credits on a subscription, $30 per 1,000 on pay-as-you-go. Organization-specific pricing may differ, and the checkout amount is authoritative.
• Safe retries need an idempotencyKey. Send a unique key (1–255 characters) with each purchase and reuse it if you retry; we charge once per key. Without a key, every call is a new purchase, so a retried timeout can charge you twice.
• Pass subscriptionId (from a credit balance check) when your organization has more than one subscription or you're charging a saved card. The response includes centsSpent, the dollar amount actually charged.
• No card on file? Pay with a one-time payment authorization (sharedPaymentGrantedToken) instead. It's billed at the pay-as-you-go rate, can't be combined with subscriptionId, and each purchase needs a fresh authorization.
• Rate limit: 2 requests/minute. Deliberately low, because this endpoint charges real money.

Example purchase:

{
  "apiKey": "sk_live_...",
  "creditsToBuy": 5000,
  "idempotencyKey": "topup-2026-10-09-001"
}

If a purchase fails:

Auto top-up

Manual top-ups don't scale to high-volume API usage — one burst of parallel jobs can drain a balance before anyone notices. Auto top-up removes the cliff: when your balance dips below a threshold you choose, Fiber automatically charges your card and adds credits, keeping jobs running without intervention.

Configure auto top-up over the API (POST /v1/auto-topup/configure) and read the settings back (GET /v1/auto-topup/settings):

Good to know:

• Settings are per subscription, not per organization. Each carries its own subscriptionId, so an org with several subscriptions configures each one separately, and reading the settings back returns a list. A subscription that has never been configured returns configured: false.
• Hitting a cap pauses, it doesn't disable. Daily caps release when the rolling window passes; monthly caps release at the start of the next calendar month. Manual purchases never count against either.
• Refills land within moments of your balance crossing the threshold, not on a nightly schedule.
• Three failed top-ups in a row (an expired card, say) disable auto top-up for that subscription, so it stops retrying a card that can't be charged. Fix the card, then turn it back on.
• When you update settings, omit a cap to keep it, or send null to remove it.
• It never un-pauses a paused account. If your subscription is paused, auto top-up won't charge you — reactivation is always an explicit action.
• Auto top-up and automatic cycle resets are mutually exclusive on the same subscription. Turning one on means the other stops firing for that subscription; different subscriptions in the same org can use different strategies.

Early reset & plan changes

Two situations restart your billing period now instead of at its natural end:

• Plan change — switching tiers starts a fresh period from the moment of the switch, with no proration: you aren't charged for unused time on the old plan and don't get partial credit for it either.
• Early reset — you can also deliberately start a fresh period early, reactivating a paused account this way if needed.

Use an early reset when you've exhausted your allocation mid-cycle and want the new period's credits immediately rather than topping up à la carte — which one is cheaper depends on your volume, so compare against the top-up rate first.

Other things worth knowing

• You get a 14-day grace period. When a usage period ends, credits stay usable for 14 days before restrictions apply, so in-flight work isn't cut off at the boundary and a renewal landing inside that window rolls over cleanly.
• Trials start with credits up to 500. Dashboard trials grant 500; cardless agent-API trials start at 100, and attaching a card raises the ceiling to 500.
• You'll hear before you run dry. API responses carry a lowCreditAlert once your balance is 500 credits or less, and a low-balance email and in-app notification goes out when you're down to 10% of your allocation.
• Everything is visible. fiber.ai/app/usage shows credits used, exported rows, and every API call; fiber.ai/app/subscription handles plans, balances, and top-up settings.
• Check balance programmatically. GET /v1/get-org-credits?apiKey=xxx is free — poll it around big jobs if you want hard guarantees before fanning out.
• Trust chargeInfo, not estimates. Published rates are representative; the chargeInfo on each response is what was actually charged.

Cost-control levers

• Size before you spend. Use the *Count endpoints (1 credit each) and free audience cost estimates to iterate on filters before pulling results.
• Cap volumes. Set sensible limits on every bulk job: maxCompanies, maxProspects, maxProspectsToEnrich, maxRowsToExport, Tracker refresh interval, Google Maps "Max locations".
• Give each key a budget. Set a per-key credit limit so a contractor, cron job, or staging environment can't spend the whole org balance. See Per-key credit limits.
• Scope enrichment. Request only the enrichmentType fields you need — skipping personal emails or phone numbers saves credits.
• Pick the right stack. For reveals, start with Lite or Normal and escalate only when needed — see the decision ladder.
• Prefer batch/audience flows over many single calls for bulk work — fewer, larger jobs are cheaper to orchestrate and easier to reconcile.
• Read your real prices. A credit balance check returns creditsPerOperation for your organization; budget against that rather than the table above.

Related

• Pricing by operation — default price of every operation, and volume pricing.
• Payment troubleshooting — fixes for common payment and billing problems.
• Search — per-result pricing and the 1-credit count endpoints.
• Live Fetch — what a fetch costs and when a not-found still counts.
• Contact Reveal — stacks and how reveal billing actually charges.