OpenSERP Cloud uses credits as the unit of billing. Every billable request consumes credits; credits do not expire. Top up in Top up.

The current baseline is $0.009 per credit. A standard single-engine search page is 1 credit, so 1,000 standard searches cost about $9 before top-up bonuses.

The current per-credit price and exact per-operation cost are always available live from the API, the pricing page, and the pricing dashboard - fetch from /v1/pricing instead of hardcoding values.

How requests turn into credits

For dynamic charges, the response is the source of truth — read X-Credits-Used (or client.lastResponse?.credits?.used) on every billable call.

Reading live pricing

/v1/pricing returns the current per-credit price and per-operation cost in one call:

const pricing = await client.pricing();
console.log(pricing.credit_price_usd);
console.log(pricing.search.credits, pricing.fast_search.credits);

curl https://api.openserp.org/v1/pricing \
  -H "Authorization: Bearer $OPENSERP_KEY"

{
  "credit_price_usd": 0.009,
  "search":      { "credits": 1 },
  "mega_search": { "credits": 1 },
  "image_search":{ "credits": 1 },
  "any_search":  { "credits": 1 },
  "fast_search": { "credits": 1 },
  "any_image":   { "credits": 1 },
  "fast_image":  { "credits": 1 }
}

If your app displays expected cost to your own users, fetch /v1/pricing periodically instead of hardcoding a rate.

Top-up bonuses

Volume top-ups add bonus credits, starting at +5% from $15. Alpha founder accounts get an additional +15% credits on every top-up, stacked with volume bonuses and capped so the effective credit price never drops below half of list price.

What counts as billable

You are charged only when the API successfully performs a search.

For balanced mega endpoints, the final charge depends on which engines succeeded and how many results they returned. For Any/Fast endpoints, an all-engines-failed response is 502 and isn’t charged.

Reading credit usage

Every billable response includes:

With the JavaScript SDK:

const response = await client.fastSearch({
  text: "openserp api",
  engines: ["google", "bing"],
});

console.log("results:",   response.results.length);
console.log("used:",      client.lastResponse?.credits?.used);
console.log("remaining:", client.lastResponse?.credits?.remaining);
console.log("engine:",    client.lastResponse?.engineUsed);

With raw fetch:

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.OPENSERP_KEY}` },
});

console.log("used:",      res.headers.get("X-Credits-Used"));
console.log("remaining:", res.headers.get("X-Credits-Remaining"));
console.log("engine:",    res.headers.get("X-Engine-Used"));

If you pass costs through to your own users, log X-Credits-Used per request and reconcile against the dashboard.

Running out of credits

When your balance reaches zero, billable calls return 402 Payment Required:

{
  "error": "insufficient_credits",
  "code": 402,
  "message": "Insufficient credits. Top up to continue."
}

The response is not charged. Top up in Top up — credits are available immediately after payment.

To avoid interruptions:

1. Watch X-Credits-Remaining in production jobs and alert below a threshold.
2. Keep a balance buffer for scheduled or high-volume searches.
3. Prefer Any/Fast endpoints when predictable 1-credit billing matters more than merged coverage.

Next

• Endpoints reference — paths and parameters.
• Errors & rate limits — retry behavior and status codes.