Credits

Credits are how Gyrence meters usage. Every successful API call draws down the calling workspace's credit balance; every failure that didn't do real work is free. The schedule is flat, transparent, and tied to the actual cost of executing the call — not to which plan you're on or how recently you signed up.

The schedule

There is no per-request surcharge, no monthly minimum, and no rounding-up of partial work.

HTTP tier vs. browser tier

Fetch, gyre, and extract all use the same two-tier fetcher:

• HTTP tier is a plain HTTP GET. Cheap and fast — works for the majority of pages on the open web.
• Browser tier runs the page in a real headless browser with JavaScript executed. Used when the HTTP tier returns a soft block (403/429/503), when the response is suspiciously small, or when the page is a JS shell with no rendered content. The endpoint escalates automatically; you don't pick a tier per call.

You can force the browser tier by passing forceBrowser: true on /fetch and /extract — useful when you already know the target needs JS and want to skip the cheap-tier attempt.

What costs what, exactly

Fetch. One credit if the HTTP tier returns a usable response; three credits if the request escalated (or was forced) to the browser tier. Forced browser-tier always bills 3.

Search. Two credits for the search itself (Brave Search is our dominant variable cost at ~$0.005/call, so the base is 2 to keep unit economics intact). If you set fetch: true, each fetched result bills at its own tier (so a 5-result search where 2 results needed the browser is 2 + 1 + 1 + 1 + 3 + 3 = 11).

Gyre. Per-page billing across the response's pages[] array: 1 per HTTP-tier page, 3 per browser-tier page, with a 1-credit minimum even if zero pages succeed. Pages that errored or were blocked land in errors[] and are free — they don't count against the budget or the bill.

Map. A flat 1 credit regardless of how many URLs come back. Map prefers the sitemap and doesn't fetch page content, so it stays cheap.

Extract. Higher base cost than fetch because every successful call also runs a model pass against the page. 5 for HTTP-tier, 7 for browser-tier.

Health. Free, always. Use it for liveness probes and key validation without burning credits.

What's never charged

• Auth failures (401) — the request never reached the primitive.
• SSRF blocks (403 forbidden_url) — refused before any fetch.
• Bad input (400 bad_request) — schema validation rejection.
• Timeouts (408) — the 25-second hard deadline tripped before useful work completed.
• Upstream errors (502 upstream_error) — origin returned a 5xx; we didn't get the content you asked for.
• Rate limits (429) — Gyrence-side throttling; you didn't get anything, so you don't pay.

The rule is: if the response doesn't include the data you asked for, you weren't billed. The one exception is the gyre 1-credit floor, which exists so a request that returns zero pages still records as a metered call.

Where credits live

Credits are a single pool on each workspace. Every key on the workspace draws from the same pool; there is no per-key allocation. Top-ups, plan grants, and refunds all apply at the workspace level.

You can watch the balance — and the events drawing it down — at Console → Usage (totals and trends) and Console → Activity (event-by-event log with cost and tier).

Estimating spend

A few sanity-check numbers for the back-of-the-napkin:

• A docs gyre with 50 pages, all HTTP tier: 50 credits.
• A search with 10 results and fetch: true, mixed tiers (~30% browser): roughly 2 + (7×1) + (3×3) = 18 credits.
• An extract over a JS-heavy product page (browser tier): 7 credits.
• A liveness check from a cron job, once a minute: 0 credits (use /health).
• The same calls over MCP: identical to the rows above. Transport doesn't change cost.

Common patterns

• Use /health for warm-up and validation. Free. Confirms the key is alive and the platform is reachable before you start spending.
• Map first, then fetch selectively. When you only need a handful of pages from a large site, run /map (1 credit) to find the URLs, then /fetch the specific ones you want. Cheaper than a wide gyre.
• Inline fetch: true on search when you'll fetch every result anyway. One round-trip, same total credits, half the latency.
• Skip forceBrowser until you know you need it. The auto-escalation only charges browser-tier when it actually runs the browser. Forcing it gives up the cheap-tier savings.