> ## Documentation Index
> Fetch the complete documentation index at: https://outcrawl.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Credits

> The metering unit behind every rate, where your credits come from, and the order they are spent in.

export const OutcrawlStyles = () => {
  if (typeof document !== 'undefined' && !document.getElementById('outcrawl-overrides')) {
    const s = document.createElement('style');
    s.id = 'outcrawl-overrides';
    s.textContent = `
      /* Match the product's radius grid (4 / 6 / 8 / 9999), not Mintlify's default. */
      .rounded-sm { border-radius: 0.375rem !important; } /* 6px, --r-ctl */
      .rounded-md { border-radius: 0.375rem !important; } /* 6px, --r-ctl */
      .rounded-lg { border-radius: 0.5rem !important; }   /* 8px, --r-panel */
      .rounded-l-sm { border-top-left-radius: 0.375rem !important; border-bottom-left-radius: 0.375rem !important; }
      .rounded-r-sm { border-top-right-radius: 0.375rem !important; border-bottom-right-radius: 0.375rem !important; }
      .rounded-l-md { border-top-left-radius: 0.375rem !important; border-bottom-left-radius: 0.375rem !important; }
      .rounded-r-md { border-top-right-radius: 0.375rem !important; border-bottom-right-radius: 0.375rem !important; }
      .rounded-l-lg { border-top-left-radius: 0.5rem !important; border-bottom-left-radius: 0.5rem !important; }
      .rounded-r-lg { border-top-right-radius: 0.5rem !important; border-bottom-right-radius: 0.5rem !important; }

      /* Cards: never pure white in light mode, matching the one-big-card surface tone. */
      .card { background-color: #fcfcfc !important; border-radius: 0.5rem !important; }
      html.dark .card { background-color: #141311 !important; }

      /* Docs hero box */
      .oc-hero { background-color: #fcfcfc; border: 1px solid #e5e2dc; }
      html.dark .oc-hero { background-color: #141311; border-color: #26241f; }
      html.dark .oc-hero h1 { color: #edeae4; }

      /* Thin, transparent-track, hide-until-hover scrollbar. */
      ::-webkit-scrollbar { width: 6px; height: 6px; background-color: transparent; }
      ::-webkit-scrollbar-track { background-color: transparent; }
      ::-webkit-scrollbar-thumb { background-color: rgba(155, 155, 155, 0.5); border-radius: 10px; transition: opacity 0.3s ease; opacity: 0; }
      ::-webkit-scrollbar-thumb:hover { background-color: rgba(155, 155, 155, 0.7); }
      *:hover::-webkit-scrollbar-thumb,
      *:focus::-webkit-scrollbar-thumb,
      *:active::-webkit-scrollbar-thumb { opacity: 1; }
      * { scrollbar-width: thin; scrollbar-color: rgba(155, 155, 155, 0.5) transparent; }
    `;
    document.head.appendChild(s);
  }
  return null;
};

<OutcrawlStyles />

A credit is the unit every rate on the [pricing page](/docs/billing/pricing) is quoted in. Every scrape, crawl, search, browser minute, agent run and monitor check draws from one spendable figure, and that figure is the one **[https://outcrawl.ai/console/billing](https://outcrawl.ai/console/billing)** shows as credits left: a request is refused only when it reaches zero.

## Where credits come from

* **Your plan's allowance.** 1,000 on Free, 10,000 on Builder, 50,000 on Pro, 250,000 on Scale. On a paid plan it is added once for each billing period you pay for, on the day the invoice is paid, and lasts until that period ends, plus 24 hours: the renewal is charged in that time, so the next period's credits arrive before the last period's run out. On Free it renews on the 1st of each month (UTC). Unused allowance does not roll over.
* **Credits you buy.** A top-up, by hand or automatic (below). Bought credits never expire.
* **Credits we grant.** A promotional, student or support grant. A grant may carry its own expiry, shown beside it on the billing page.

## The order they are spent in

Spending always draws from whatever expires soonest, so nothing lapses unused while something longer-lived is spent instead. In practice:

1. this period's plan allowance first,
2. then grants with an expiry, the soonest-expiring first (a grant that ends before your period does is spent before the allowance),
3. then credits that never expire: everything you bought.

So a top-up is only touched once the current period's allowance is used up, and whatever is left of it carries into the next period untouched.

## Buying credits

Add credits from **[https://outcrawl.ai/console/billing](https://outcrawl.ai/console/billing)** on any plan, whether you are paying for one or not. A paid plan buys at its own price per credit: $49.00 per 10,000 on Builder, $39.80 on Pro, $31.96 on Scale. Free and paused workspaces buy at the Builder rate. A purchase is 100 to 1,000,000 credits and at least $0.50, and the credits are added the moment the payment succeeds.

## Auto top-up

Auto top-up buys credits for you before you run out. A workspace owner or admin sets it up on **[https://outcrawl.ai/console/billing](https://outcrawl.ai/console/billing)** with three numbers:

* **Threshold:** charge when spendable credits drop below this. Suggested: a fifth of your plan's monthly credits.
* **Amount:** how many credits to buy each time, at the same price as buying them by hand. Suggested: one month of your plan's credits.
* **Monthly cap:** the most auto top-up may charge in one calendar month (UTC), counting a charge still in progress. Suggested: four top-ups' worth. It must cover at least one.

Spendable credits are checked every minute. Below the threshold, your default card is charged for the amount, and the credits are added as soon as the payment succeeds; they never expire. Only one auto top-up runs at a time for a workspace, and each one is charged at most once, however often the check runs. Once the next one would take the month past the cap, auto top-up waits for the next month instead. While your plan's renewal is being charged (up to two hours after its invoice is created), auto top-up waits too: the new period's credits are about to arrive.

It needs a default card on the workspace. If a charge is declined, or your bank asks to confirm it (which an automatic charge cannot do), auto top-up turns itself off, the billing page says why, and every workspace owner gets an email. The same happens if a single top-up comes to cost more than the monthly cap, for example after a pause or downgrade moves the workspace to a higher price per credit. Nothing is retried on the same card until someone turns it back on. Saving the settings never charges by itself: if credits are already below the new threshold, the first top-up follows within a minute.

## Refunds and disputes

A refund takes back the credits the refunded payment added, in proportion to the amount refunded, rounded in your favour. Refunding a top-up removes that share of its credits; refunding a plan invoice removes that share of its period's allowance, unless the period has already ended. A disputed payment's credits are removed while the dispute is open and added back if it is resolved in your favour.

The share taken back comes out of credits still on the balance first: what is left of the credits that payment added (the refunded period's allowance, for a plan invoice), then your other credits, purchased credits included. Only what the balance cannot cover is owed, and the next credits that arrive, from a renewal, a purchase or a grant, pay that first.

A refund of an auto top-up, or a dispute on any payment, also turns auto top-up off and emails the workspace owners, so the card is not charged again for the credits just taken back.

## Reading your balance

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
  import { Outcrawl } from '@outcrawl/sdk';

  const oc = new Outcrawl();
  const credits = await oc.credits();
  console.log(credits.granted, credits.spent, credits.balance); // decimal strings
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
  import asyncio
  from outcrawl import Outcrawl

  async def main() -> None:
      async with Outcrawl() as oc:
          credits = await oc.credits()
          print(credits.granted, credits.spent, credits.balance)  # decimal strings

  asyncio.run(main())
  ```

  ```bash curl theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
  curl https://api.outcrawl.ai/v1/credits -H "Authorization: Bearer ock_YOUR_KEY_ID.YOUR_SECRET"
  ```
</CodeGroup>

`credits` returns four decimal strings for the credits recorded on your account: paid plan periods, purchases and grants. `granted` is what is still live, `expired` is what lapsed unused (shown on its own rather than dropped), `spent` is everything metered, and `balance` is what remains of the live credits after any amount owed. Free's monthly allowance is not a recorded grant, so it is not counted there; the credits left on the billing page include it. Per-call cost is on every response already, see [usage](/docs/billing/usage).

## Changing plan mid month

An upgrade starts a new monthly billing period on the day you make it. It charges the new plan's
full month today, less a credit for the unused time on your current plan, and your billing date
moves to today. That charge adds the same share of the new plan's monthly allowance, at the new
plan's rate: the unused time on the old plan comes back to you as money, so it is not paid for
again in credits. Whatever is left of the old plan's credits stays usable until the date that
period would have ended, and is spent first. A full month's allowance comes only with a full
month's invoice: the first payment on a new subscription, every renewal after it, and resuming a
paused plan with a charge. A downgrade takes effect at the end of the period you already paid for
and charges nothing when it lands; the lower plan's allowance arrives with its first renewal.

Each invoice adds credits at most once. Retrying a payment, or Stripe redelivering the same
webhook, never adds them twice for the same invoice.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.