# Scrapfly Documentation

## Table of Contents

### Dashboard

- [Intro](https://scrapfly.io/docs)
- [Project](https://scrapfly.io/docs/project)
- [Account](https://scrapfly.io/docs/account)
- [Workspace & Team](https://scrapfly.io/docs/workspace-and-team)
- [Billing](https://scrapfly.io/docs/billing)

### Products

#### MCP Server

- [Getting Started](https://scrapfly.io/docs/mcp/getting-started)
- [Tools & API Spec](https://scrapfly.io/docs/mcp/tools)
- [Authentication](https://scrapfly.io/docs/mcp/authentication)
- [Examples & Use Cases](https://scrapfly.io/docs/mcp/examples)
- [FAQ](https://scrapfly.io/docs/mcp/faq)
##### Integrations

- [Overview](https://scrapfly.io/docs/mcp/integrations)
- [Claude Desktop](https://scrapfly.io/docs/mcp/integrations/claude-desktop)
- [Claude Code](https://scrapfly.io/docs/mcp/integrations/claude-code)
- [ChatGPT](https://scrapfly.io/docs/mcp/integrations/chatgpt)
- [Cursor](https://scrapfly.io/docs/mcp/integrations/cursor)
- [Cline](https://scrapfly.io/docs/mcp/integrations/cline)
- [Windsurf](https://scrapfly.io/docs/mcp/integrations/windsurf)
- [Zed](https://scrapfly.io/docs/mcp/integrations/zed)
- [Roo Code](https://scrapfly.io/docs/mcp/integrations/roo-code)
- [VS Code](https://scrapfly.io/docs/mcp/integrations/vscode)
- [LangChain](https://scrapfly.io/docs/mcp/integrations/langchain)
- [LlamaIndex](https://scrapfly.io/docs/mcp/integrations/llamaindex)
- [CrewAI](https://scrapfly.io/docs/mcp/integrations/crewai)
- [OpenAI](https://scrapfly.io/docs/mcp/integrations/openai)
- [n8n](https://scrapfly.io/docs/mcp/integrations/n8n)
- [Make](https://scrapfly.io/docs/mcp/integrations/make)
- [Zapier](https://scrapfly.io/docs/mcp/integrations/zapier)
- [Vapi AI](https://scrapfly.io/docs/mcp/integrations/vapi)
- [Agent Builder](https://scrapfly.io/docs/mcp/integrations/agent-builder)
- [Custom Client](https://scrapfly.io/docs/mcp/integrations/custom-client)


#### Web Scraping API

- [Getting Started](https://scrapfly.io/docs/scrape-api/getting-started)
- [API Specification]()
- [Monitoring](https://scrapfly.io/docs/monitoring)
- [Customize Request](https://scrapfly.io/docs/scrape-api/custom)
- [Debug](https://scrapfly.io/docs/scrape-api/debug)
- [Anti Scraping Protection](https://scrapfly.io/docs/scrape-api/anti-scraping-protection)
- [Proxy](https://scrapfly.io/docs/scrape-api/proxy)
- [Proxy Mode](https://scrapfly.io/docs/scrape-api/proxy-mode)
- [Proxy Mode - Screaming Frog](https://scrapfly.io/docs/scrape-api/proxy-mode/screaming-frog)
- [Proxy Mode - Apify](https://scrapfly.io/docs/scrape-api/proxy-mode/apify)
- [(Auto) Data Extraction](https://scrapfly.io/docs/scrape-api/extraction)
- [Javascript Rendering](https://scrapfly.io/docs/scrape-api/javascript-rendering)
- [Javascript Scenario](https://scrapfly.io/docs/scrape-api/javascript-scenario)
- [SSL](https://scrapfly.io/docs/scrape-api/ssl)
- [DNS](https://scrapfly.io/docs/scrape-api/dns)
- [Cache](https://scrapfly.io/docs/scrape-api/cache)
- [Batch (Multi-URL Scraping)](https://scrapfly.io/docs/scrape-api/batch)
- [Session](https://scrapfly.io/docs/scrape-api/session)
- [Webhook](https://scrapfly.io/docs/scrape-api/webhook)
- [Schedule](https://scrapfly.io/docs/scrape-api/schedule)
- [Screenshot](https://scrapfly.io/docs/scrape-api/screenshot)
- [Errors](https://scrapfly.io/docs/scrape-api/errors)
- [Timeout](https://scrapfly.io/docs/scrape-api/understand-timeout)
- [Throttling](https://scrapfly.io/docs/throttling)
- [Troubleshoot](https://scrapfly.io/docs/scrape-api/troubleshoot)
- [Billing](https://scrapfly.io/docs/scrape-api/billing)
- [FAQ](https://scrapfly.io/docs/scrape-api/faq)

#### Crawler API

- [Getting Started](https://scrapfly.io/docs/crawler-api/getting-started)
- [API Specification]()
- [Retrieving Results](https://scrapfly.io/docs/crawler-api/results)
- [WARC Format](https://scrapfly.io/docs/crawler-api/warc-format)
- [Data Extraction](https://scrapfly.io/docs/crawler-api/extraction-rules)
- [Webhook](https://scrapfly.io/docs/crawler-api/webhook)
- [Schedule](https://scrapfly.io/docs/crawler-api/schedule)
- [Billing](https://scrapfly.io/docs/crawler-api/billing)
- [Errors](https://scrapfly.io/docs/crawler-api/errors)
- [Troubleshoot](https://scrapfly.io/docs/crawler-api/troubleshoot)
- [FAQ](https://scrapfly.io/docs/crawler-api/faq)

#### Screenshot API

- [Getting Started](https://scrapfly.io/docs/screenshot-api/getting-started)
- [API Specification]()
- [Accessibility Testing](https://scrapfly.io/docs/screenshot-api/accessibility)
- [Webhook](https://scrapfly.io/docs/screenshot-api/webhook)
- [Schedule](https://scrapfly.io/docs/screenshot-api/schedule)
- [Billing](https://scrapfly.io/docs/screenshot-api/billing)
- [Errors](https://scrapfly.io/docs/screenshot-api/errors)

#### Extraction API

- [Getting Started](https://scrapfly.io/docs/extraction-api/getting-started)
- [API Specification]()
- [Rules Template](https://scrapfly.io/docs/extraction-api/rules-and-template)
- [LLM Extraction](https://scrapfly.io/docs/extraction-api/llm-prompt)
- [AI Auto Extraction](https://scrapfly.io/docs/extraction-api/automatic-ai)
- [Webhook](https://scrapfly.io/docs/extraction-api/webhook)
- [Billing](https://scrapfly.io/docs/extraction-api/billing)
- [Errors](https://scrapfly.io/docs/extraction-api/errors)
- [FAQ](https://scrapfly.io/docs/extraction-api/faq)

#### Data API


#### Proxy Saver

- [Getting Started](https://scrapfly.io/docs/proxy-saver/getting-started)
- [Fingerprints](https://scrapfly.io/docs/proxy-saver/fingerprints)
- [Optimizations](https://scrapfly.io/docs/proxy-saver/optimizations)
- [SSL Certificates](https://scrapfly.io/docs/proxy-saver/certificates)
- [Protocols](https://scrapfly.io/docs/proxy-saver/protocols)
- [Pacfile](https://scrapfly.io/docs/proxy-saver/pacfile)
- [Secure Credentials](https://scrapfly.io/docs/proxy-saver/security)
- [Billing](https://scrapfly.io/docs/proxy-saver/billing)

#### Cloud Browser API

- [Getting Started](https://scrapfly.io/docs/cloud-browser-api/getting-started)
- [Proxy & Geo-Targeting](https://scrapfly.io/docs/cloud-browser-api/proxy)
- [Unblock API](https://scrapfly.io/docs/cloud-browser-api/unblock)
- [Captcha Solver](https://scrapfly.io/docs/cloud-browser-api/captcha-solver)
- [File Downloads](https://scrapfly.io/docs/cloud-browser-api/file-downloads)
- [Session Resume](https://scrapfly.io/docs/cloud-browser-api/session-resume)
- [Human-in-the-Loop](https://scrapfly.io/docs/cloud-browser-api/human-in-the-loop)
- [Debug Mode](https://scrapfly.io/docs/cloud-browser-api/debug-mode)
- [Browser Extensions](https://scrapfly.io/docs/cloud-browser-api/extensions)
- [Native Browser MCP](https://scrapfly.io/docs/cloud-browser-api/mcp)
- [DevTools Protocol](https://scrapfly.io/docs/cloud-browser-api/cdp-reference)
##### Integrations

- [Puppeteer](https://scrapfly.io/docs/cloud-browser-api/puppeteer)
- [Playwright](https://scrapfly.io/docs/cloud-browser-api/playwright)
- [Selenium](https://scrapfly.io/docs/cloud-browser-api/selenium)
- [Vercel Agent Browser](https://scrapfly.io/docs/cloud-browser-api/agent-browser)
- [Browser Use](https://scrapfly.io/docs/cloud-browser-api/browser-use)
- [Stagehand](https://scrapfly.io/docs/cloud-browser-api/stagehand)

- [Billing](https://scrapfly.io/docs/cloud-browser-api/billing)
- [Errors](https://scrapfly.io/docs/cloud-browser-api/errors)


### Tools

- [Antibot Detector](https://scrapfly.io/docs/tools/antibot-detector)

### SDK

- [Golang](https://scrapfly.io/docs/sdk/golang)
- [Python](https://scrapfly.io/docs/sdk/python)
- [Rust](https://scrapfly.io/docs/sdk/rust)
- [TypeScript](https://scrapfly.io/docs/sdk/typescript)
- [Scrapy](https://scrapfly.io/docs/sdk/scrapy)

### Integrations

- [Getting Started](https://scrapfly.io/docs/integration/getting-started)
- [LangChain](https://scrapfly.io/docs/integration/langchain)
- [LlamaIndex](https://scrapfly.io/docs/integration/llamaindex)
- [CrewAI](https://scrapfly.io/docs/integration/crewai)
- [Zapier](https://scrapfly.io/docs/integration/zapier)
- [Make](https://scrapfly.io/docs/integration/make)
- [n8n](https://scrapfly.io/docs/integration/n8n)

### Academy

- [Overview](https://scrapfly.io/academy)
- [Web Scraping Overview](https://scrapfly.io/academy/scraping-overview)
- [Tools](https://scrapfly.io/academy/tools-overview)
- [Reverse Engineering](https://scrapfly.io/academy/reverse-engineering)
- [Static Scraping](https://scrapfly.io/academy/static-scraping)
- [HTML Parsing](https://scrapfly.io/academy/html-parsing)
- [Dynamic Scraping](https://scrapfly.io/academy/dynamic-scraping)
- [Hidden API Scraping](https://scrapfly.io/academy/hidden-api-scraping)
- [Headless Browsers](https://scrapfly.io/academy/headless-browsers)
- [Hidden Web Data](https://scrapfly.io/academy/hidden-web-data)
- [JSON Parsing](https://scrapfly.io/academy/json-parsing)
- [Data Processing](https://scrapfly.io/academy/data-processing)
- [Scaling](https://scrapfly.io/academy/scaling)
- [Walkthrough Summary](https://scrapfly.io/academy/walkthrough-summary)
- [Scraper Blocking](https://scrapfly.io/academy/scraper-blocking)
- [Proxies](https://scrapfly.io/academy/proxies)

---

#  Metric Reference

 Every metric listed here can be used as the target of an alert rule. Pick a metric in the alert create wizard and the form automatically shows only the dimension filters that metric supports.

 The metric catalog is fixed. Only the metric IDs listed on this page are accepted; any other value is rejected at alert creation with [`ERR::ALERT::UNKNOWN_METRIC`](https://scrapfly.io/docs/alerting/error-reference).

 The full catalog is also available programmatically at `GET /alert/metric-families`. The response schema is the same as the table on this page, so you can drive a UI or validation layer from the live list rather than hard-coding metric IDs in your own code.

## Web Scraping API

 Web Scraping metrics evaluate at 5-minute granularity. Metrics scoped per-domain expose the `root_domain` dimension; project-wide metrics expose `env` and `origin`.

 | Metric ID | Display name | Unit | Default sustained window | Allowed dimensions | Notes |
|---|---|---|---|---|---|
| `scrape.success_rate` | Success rate | % | 5 min | `env`, `origin`, `root_domain` | Percentage of requests that succeeded. Alert on a drop below your expected floor (use *less than* comparator). |
| `scrape.block_rate` | Block rate (ASP + status) | % | 5 min | `env`, `origin`, `root_domain` | Requests blocked by anti-bot protections or status codes 403, 429, 444, 999, 428, 503, 499, or any `ERR::ASP::*` error prefix. |
| `scrape.asp_errors_per_min` | ASP errors (window total) | count | 5 min | `env`, `origin` | Total ASP errors over the evaluation window. |
| `scrape.requests_per_min` | Throughput (window total) | count | 5 min | `env`, `origin` | Total requests over the evaluation window. Useful for liveness checks ("my scraper should be firing at least N requests every 5 minutes"). |
| `scrape.cost_per_min` | API credits (window total) | credits | 5 min | `env`, `origin` | Total API credits consumed over the evaluation window. Alert on unexpectedly high spend. |
| `scrape.credits_per_hour` | Credits / hour | credits/hour | 60 min | `env` | Total billed Scrapfly credits consumed by the Web Scraping API over the window. Useful for hourly budget enforcement. |
| `scrape.avg_credits_per_request` | Average credits per scrape | credits/request | 60 min | `env`, `origin` | Average billed Scrapfly credits per scrape request. Useful when configuration changes (ASP, render\_js, premium proxies) push per-request cost beyond expectation. |
| `scrape.duration_p95` | Average latency | ms | 5 min | `env`, `origin` | Average scrape latency over the window. |
| `scrape.5xx_rate` | Failure rate | % | 5 min | `env`, `origin` | Percentage of requests that failed for any reason. |

## Cloud Browser

 Cloud Browser metrics evaluate at 30-minute granularity. The default sustained window is 30 minutes because shorter windows see noise from single-session variance.

 | Metric ID | Display name | Unit | Default sustained window | Allowed dimensions | Notes |
|---|---|---|---|---|---|
| `cb.session_success_rate` | Session success rate | % | 30 min | `env`, `proxy_pool` | Percentage of browser sessions that completed without an error. |
| `cb.bandwidth_per_hour` | Bandwidth / hour | bytes/hour | 30 min | `env`, `proxy_pool` | Total bytes transferred by browser sessions in the evaluation window. Alert on unexpected bandwidth spikes. |
| `cb.error_count` | Error count | count | 30 min | `env`, `proxy_pool` | Total browser session errors in the evaluation window. |
| `cb.runs_per_hour` | Runs / hour | count/hour | 60 min | `env`, `proxy_pool` | Number of Cloud Browser sessions started over the window. Liveness check (drops to zero) or runaway guard (spikes beyond baseline). |
| `cb.avg_run_time_ms` | Average session duration | ms | 60 min | `env`, `proxy_pool` | Average duration of Cloud Browser sessions over the window. Alert when sessions run longer than expected (often a sign of stuck pages or runaway scripts). |
| `cb.avg_bandwidth_per_run` | Average bandwidth per session | bytes/run | 60 min | `env`, `proxy_pool` | Average bytes transferred per Cloud Browser session over the window. Useful when unexpectedly heavy pages need an aborted-resource policy. |
| `cb.credits_per_hour` | Credits / hour | credits/hour | 60 min | `env` | Total billed Scrapfly credits consumed by Cloud Browser sessions over the window. Includes RPA-driven sessions, which are billed as Cloud Browser usage plus a separate RPA line for LLM tokens. |

## Proxy Saver

 Proxy Saver metrics evaluate at 5-minute granularity. The `proxy_saver_uuid` dimension lets you scope an alert to a single Proxy Saver instance.

 | Metric ID | Display name | Unit | Default sustained window | Allowed dimensions | Notes |
|---|---|---|---|---|---|
| `proxy_saver.backconnect_failure_rate` | Back-connect failure rate | % | 5 min | `proxy_saver_uuid` | Percentage of back-connect attempts that failed. |
| `proxy_saver.blocked_requests_per_min` | Blocked requests / min | count | 5 min | `proxy_saver_uuid` | Rate of blocked requests per minute through the instance. |

## BYOP (Bring Your Own Proxy)

 BYOP metrics are account-scoped (not per-project) because connector transfers are not tied to a single project. The `connector_short_id` dimension lets you scope an alert to one connector.

 | Metric ID | Display name | Unit | Default sustained window | Allowed dimensions | Notes |
|---|---|---|---|---|---|
| `byop.transfer_refused_rate` | BYOP transfer refused rate | % | 5 min | `connector_short_id` | Percentage of BYOP connector transfers that the relay refused. |

## Extraction API

 Extraction API metrics evaluate at 5-minute granularity for the failure rate and 60-minute granularity for credit metrics.

 | Metric ID | Display name | Unit | Default sustained window | Allowed dimensions | Notes |
|---|---|---|---|---|---|
| `extraction.failure_rate` | Extraction failure rate | % | 5 min | `env` | Percentage of Extraction API requests that failed. |
| `extraction.credits_per_hour` | Credits / hour | credits/hour | 60 min | `env` | Total billed Scrapfly credits consumed by the Extraction API over the window. Useful for hourly budget enforcement. |
| `extraction.avg_credits_per_request` | Average credits per extraction | credits/request | 60 min | `env` | Average billed Scrapfly credits per extraction request. Useful when prompt or template changes inflate per-request cost. |

## Scheduler

 Scheduler metrics evaluate at the granularity of each individual schedule execution. The `schedule_uuid` dimension lets you scope an alert to a single schedule.

 | Metric ID | Display name | Unit | Default sustained window | Allowed dimensions | Notes |
|---|---|---|---|---|---|
| `scheduler.failure_rate` | Schedule failure rate | % | 5 min | `schedule_uuid` | Percentage of schedule executions that ended in `FAILED` status. |
| `scheduler.no_executions` | Schedule went silent | count | 30 min | `schedule_uuid` | Fires when a schedule has produced zero executions in the window. Pair with [no-data policy](https://scrapfly.io/docs/alerting/state-machine#no-data-policy) set to **triggered** for a liveness monitor. |

## Crawler API

 Reads from `user_api_credit_usage` at 1-hour grain, filtered to `service = crawler_api`.

 | Metric ID | Display name | Unit | Default sustained window | Allowed dimensions | Notes |
|---|---|---|---|---|---|
| `crawler.credits_per_hour` | Credits / hour | credits/hour | 60 min | `env` | Total billed Scrapfly credits consumed by the Crawler API over the window. Hourly budget enforcement. |

## Screenshot API

 Reads from `user_api_credit_usage` at 1-hour grain, filtered to `service = screenshot_api`.

 | Metric ID | Display name | Unit | Default sustained window | Allowed dimensions | Notes |
|---|---|---|---|---|---|
| `screenshot.credits_per_hour` | Credits / hour | credits/hour | 60 min | `env` | Total billed Scrapfly credits consumed by the Screenshot API over the window. Hourly budget enforcement. |

## API Errors

 Error metrics evaluate at 60-minute granularity. The `error_code` dimension lets you target a single error code (for example, [`ERR::ASP::SHIELD_ERROR`](https://scrapfly.io/docs/scrape-api/errors#asp)).

 | Metric ID | Display name | Unit | Default sustained window | Allowed dimensions | Notes |
|---|---|---|---|---|---|
| `errors.code_rate` | Specific error code rate | count/hour | 60 min | `error_code`, `env`, `origin` | Count of a specific API error code per evaluation window. Always set the `error_code` dimension; without it the metric aggregates all error codes together. |

## Billing

 Reads from `user_api_credit_usage_daily` at 1-day grain. This metric has no project or environment dimension.

 | Metric ID | Display name | Unit | Default sustained window | Allowed dimensions | Notes |
|---|---|---|---|---|---|
| `billing.daily_credit_burn` | Daily credit burn | credits/day | 1440 min (1 day) | (none) | Total API credits consumed in the current day. Alert when you approach a daily spend ceiling. The 1440-minute sustained window matches the daily grain. |

## Common dimension values

 | Dimension key | Valid values | Notes |
|---|---|---|
| `env` | `LIVE`, `TEST` | Enum; the form shows a dropdown with these two values |
| `origin` | `WEB_SCRAPING_API`, `SCREENSHOT_API`, `CRAWLER_API`, `SCHEDULER`, `WEBHOOK`, `UI` | Filters by the request origin |
| `root_domain` | Any registered root domain string (e.g. `web-scraping.dev`) | Available only on per-domain `scrape.*` metrics |
| `proxy_pool` | Pool identifier string from your proxy configuration | Cloud Browser metrics only |
| `error_code` | Any `ERR::*` code from the [error registry](https://scrapfly.io/docs/scrape-api/errors) | `errors.code_rate` only |
| `kind` | `workflow`, `agent`, `task`, `branch`, `verify` | RPA metrics only |
| `schedule_uuid` | ULID of the schedule (from the Scheduler dashboard URL) | Scheduler metrics only |
| `proxy_saver_uuid` | UUID of the Proxy Saver instance | Proxy Saver metrics only |
| `connector_short_id` | Short ID of the BYOP connector | BYOP metrics only |

 [ Getting Started ](https://scrapfly.io/docs/alerting/getting-started) [ Webhook Payload ](https://scrapfly.io/docs/alerting/webhook-payload)