Skip to main content
Your account can have up to 10 API keys, for example one per project, environment, or customer. Each key can have its own credit caps, so one workload can’t use up the credits another one needs. Manage keys and caps on the API keys page.

​
Set or change a cap

  1. Open the API keys page (Settings > API keys).
  2. Open the menu of the key you want to limit and select Credit caps.
  3. Click Add a cap, choose the Window, enter the cap in credits, and click Add cap.
To change or remove a cap, open that cap’s actions menu in the same window.

​
How caps work

A key can have any of these caps, alone or combined:
  • Keys are uncapped by default, including your main key.
  • A key with several caps stops when it reaches any of them.
  • All credits a key uses count toward its caps, overage included.
  • Browser Sessions (formerly, Scraping Browser) count too, both their time and their data.
  • Caps limit usage. They don’t reserve credits and don’t need to add up to your plan.
  • Upgrades, downgrades and top-ups don’t change your caps.

​
When a key reaches its cap

The key stops working, and your other keys keep working. How the refusal looks depends on the product: The key works again when its cap window resets, or shortly after you raise or remove the cap.

​
When the cap is checked

A cap is checked when something starts: each API request, and each Browser Session. If the key is still under its cap at that moment, the request or session goes ahead. What’s already running isn’t cut off:
  • A request in progress when the cap is reached completes.
  • A Browser Session that’s already open keeps running until it ends. Everything it uses still counts toward the cap, and the next session started with that key is refused.
So usage can go over the cap by what was already running. For normal traffic that’s a small amount. Batch runs many tasks in parallel, so a Batch run can go further over before it stops. A single session that moves a very large amount of data can take a key well past its cap before the cap stops the next one, so size caps with your heaviest sessions in mind. If the usage of a cap can’t be read for a moment, that cap doesn’t block the key until its usage is available again. Any other caps on the key still apply.
AUTH014 means one key reached its own cap. AUTH004 means your account has no credits left, which affects every key.
A key cap doesn’t guarantee zero overage charges. Your account can run out of included credits before a key reaches its cap.

​
Batch jobs

Batch jobs use the caps of the key they run with. A capped key can’t start or add to a job, a run that reaches a cap stops, and scheduled runs are checked when they start. See API key credit caps and Batch.

​
Tracking remaining credits

Responses from a key that has at least one cap include the X-Key-Credits-Remaining header: the lowest remaining credits across that key’s caps. Uncapped keys don’t get this header. If the usage of a cap can’t be read for a moment, the header leaves that cap out, and it isn’t sent at all when none of the key’s caps can be read.
Read it to slow down or switch keys before a cap stops your requests. See all response headers.

​
Alerts

Your account’s notification recipients get an email and an in-app notification when a key reaches 80% and 100% of a cap. They also get an email when a cap is set, changed, or removed. Turn these alerts on or off with the API key credit caps notification setting.

​
Residential Proxies (Legacy)

Key caps don’t apply to Residential Proxies. Residential proxy credentials keep their own limits.