Token Plan
Learn how tokens work in MrScraper and how to create your own API token for authentication.
MrScraper uses a token-based system for both usage and authentication.
- Plan Tokens measure how much you can use MrScraper's features, such as running or rerunning scrapers.
- API Tokens allow you to securely access the MrScraper API, for example, to rerun an existing scraper programmatically.
Why Token Usage Varies
Token consumption isn't fixed — a few key factors affect how many tokens any given scraper uses:
- Website Complexity: Heavy JavaScript, dynamic content, or multiple requests increase runtime and token usage.
- Page Size and Content Density: Larger pages with long articles or extensive metadata produce more input text for AI models to process.
- Data Volume: Extracting large datasets (e.g., paginated listings) requires more compute and bandwidth.
- AI Processing Load: Complex instructions or large expected outputs increase input and output token usage.
Keep these in mind as you read the pricing tables below — they explain why two runs on the same plan can consume different amounts of tokens.
Understanding Plan Tokens
Each MrScraper billing plan includes a specific number of tokens. Tokens represent the compute resources your scraper consumes — similar to how minutes or data are counted in a phone plan.
The number of tokens used depends on the type of scraper you run.
AI Scraper Token Usage
AI Scrapers consume more tokens due to AI processing and additional factors such as:
| Usage Type | Description | Conversion Rate |
|---|---|---|
| Run Tracking | Each AI agent run consumes 5 tokens for trace tracking. Reruns and manual scrapers consume 0 tokens for this component. | 0 or 5 tokens per run |
| Runtime | Time spent processing your task. | 1 token per 30 seconds of runtime |
| Input Tokens | Amount of text data (prompts or instructions) sent to the AI model. | 1 token per ~1,000 input tokens |
| Output Tokens | Amount of text generated by the AI model (responses or extracted results). | 1 token per ~200 output tokens |
Example
If your AI scraper runs for 90 seconds, processes 5,000 input tokens, and generates 1,000 output tokens, your total token usage would be:
| Component | Calculation | Tokens |
|---|---|---|
| Runtime | 90 ÷ 30 | 3 |
| Input | 5,000 ÷ 1,000 | 5 |
| Output | 1,000 ÷ 200 | 5 |
| Run Trace | Fixed | 5 |
| Total | 18 |
Note
- Each run automatically includes trace tracking for debugging and performance monitoring.
- Input and output tokens are based on how much text the AI model processes and generates.
- AI Scrapers tend to consume more tokens due to model processing.
- Runtime tokens are rounded up using the ceiling rule. For example, if your scraper runs for 40 seconds, it will count as 2 tokens (not 1).
Manual Scraper and Unblocker Token Usage
Manual Scrapers and Unblocker consume tokens based on two factors: runtime and bandwidth.
| Usage Type | Description | Conversion Rate |
|---|---|---|
| Runtime | Time your scraper runs. | 1 token per 30 seconds |
| Bandwidth | Amount of data downloaded or uploaded. | 1 token per 0.2 MB |
Example
If your manual scraper or unblocker runs for 40 seconds and uses 1.1 MB of bandwidth:
| Component | Calculation | Tokens |
|---|---|---|
| Runtime | 40 ÷ 30 = 1.33 → rounded up | 2 |
| Bandwidth | 1.1 ÷ 0.2 = 5.5 → rounded up | 6 |
| Total | 8 |
Note
Runtime tokens are rounded up using the ceiling rule. For example, if your scraper runs for 40 seconds, it will count as 2 tokens (not 1).
Playground Token Cap
The Playground token cap limits how many tokens a single scrape can use in the Playground. It applies only to Manual Scraper and Unblocker, using the same runtime and bandwidth calculations shown in Manual Scraper and Unblocker Token Usage.
When Retry is enabled, a failed scrape retries automatically. Two limits control how far retrying goes:
- Max retries: The maximum number of retry attempts (3 by default).
- Token cap: The maximum total tokens all attempts can use (Unlimited by default).
Retrying stops at the first of these: the scrape succeeds, it reaches Max retries, or the running token total reaches the token cap. Each attempt's token cost is rounded up (ceiling rule) and added to a running total.
The token cap takes effect only when Retry is enabled, since its purpose is to limit how many tokens retries can consume. If Retry is off, the scrape runs once and returns a result or an error.
Example
Max retries 3, token cap 10.
| Attempt | Runtime + Bandwidth | Rounded-up Cost | Running Total | Result |
|---|---|---|---|---|
| 1 (initial) | 2.4 tokens | 3 | 3 | Failed, retrying |
| 2 (retry 1) | 1.6 tokens | 2 | 5 | Succeeded |
The scrape succeeds on the second attempt, using 5 tokens. Because it succeeded, the Playground returns the result and stops even though max retries and tokens still remain (5 of 10 tokens left, and 2 retries unused).
Max retries 2, token cap 20.
| Attempt | Runtime + Bandwidth | Rounded-up Cost | Running Total | Result |
|---|---|---|---|---|
| 1 (initial) | 3.6 tokens | 4 | 4 | Failed, retrying |
| 2 (retry 1) | 3.8 tokens | 4 | 8 | Failed, retrying |
| 3 (retry 2) | 3.4 tokens | 4 | 12 | Failed, max retries reached |
The scrape uses both retries without succeeding, so it stops even though 8 tokens still remain under the 20-token cap.
Max retries 3, token cap 12, about 4 tokens per run.
| Attempt | Runtime + Bandwidth | Rounded-up Cost | Running Total | Result |
|---|---|---|---|---|
| 1 (initial) | 3.5 tokens | 4 | 4 | Failed, retrying |
| 2 (retry 1) | 3.9 tokens | 4 | 8 | Failed, retrying |
| 3 (retry 2) | 3.7 tokens | 4 | 12 | Failed, cap reached |
The running total reaches the 12-token cap on the second retry, so the scrape stops before using all 3 retries.
First attempt exceeds the cap
If the first attempt costs more than the cap (for example, a cap of 10 but a first scrape that needs 15 tokens), the scrape still runs once but doesn't retry.
It returns either a result or an error. Set the token cap high enough to allow for retries, especially on pages with variable load times or bandwidth. If a scrape hits the cap before completing, try increasing the cap.
Marketplace Scraper Token Usage
Marketplace Scrapers use a custom token cost based on factors such as the target domain, workflow complexity, proxy usage, infrastructure requirements, and scraper configuration. Each scraper may use either a fixed token cost or a custom usage calculation depending on how the scraper is designed.
For the complete list of Marketplace Scraper token costs, see the Marketplace catalog.
Generate a New API Token
You can also create additional tokens for different environments, applications, or use cases. To create a new API token:
-
Click your profile icon in the top-right corner of the dashboard.
-
Select API Tokens.
-
Click New Token.
-
Enter a token name and choose an expiration date.
Note
The token name is required when making requests to the analytics endpoint.
-
Click Create.
-
Copy the generated API token and store it in a secure location. You will need this token to authenticate API requests.
Keep It Secret!
Never expose your API token in client-side code (like browsers or apps). Always store it securely in an environment variable or server configuration.