{ "openapi": "3.0.0", "info": { "title": "Firecrawl API", "version": "v2", "description": "API for interacting with Firecrawl services to perform web scraping and crawling tasks.", "contact": { "name": "Firecrawl Support", "url": "https://firecrawl.dev/support", "email": "support@firecrawl.dev" } }, "servers": [ { "url": "https://api.firecrawl.dev/v2" } ], "paths": { "/scrape": { "post": { "summary": "Scrape a single URL and optionally extract information using an LLM", "operationId": "scrapeAndExtractFromUrl", "tags": ["Scraping"], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The URL to scrape" } }, "required": ["url"] }, { "$ref": "#/components/schemas/ScrapeOptions" }, { "type": "object", "properties": { "zeroDataRetention": { "type": "boolean", "default": false, "description": "If true, this will enable zero data retention for this scrape. To enable this feature, please contact help@firecrawl.dev" } } } ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeResponse" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment required to access this resource." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Request rate limit exceeded. Please wait and try again later." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "string", "example": "UNKNOWN_ERROR" }, "error": { "type": "string", "example": "An unexpected error occurred on the server." } } } } } } } } }, "/scrape/{jobId}/interact": { "post": { "summary": "Interact with the browser session associated with a scrape job", "operationId": "interactWithScrapeBrowserSession", "tags": ["Scraping"], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The scrape job ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["code"], "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "Code to execute in the scrape-bound browser sandbox" }, "language": { "type": "string", "enum": ["python", "node", "bash"], "default": "node", "description": "Language of the code to execute. Use `node` for JavaScript or `bash` for agent-browser CLI commands." }, "timeout": { "type": "integer", "minimum": 1, "maximum": 300, "default": 30, "description": "Execution timeout in seconds" }, "origin": { "type": "string", "description": "Optional origin label used for execution telemetry" } } } } } }, "responses": { "200": { "description": "Code executed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "stdout": { "type": "string", "nullable": true, "description": "Standard output from the code execution" }, "result": { "type": "string", "nullable": true, "description": "Standard output (alias for stdout)" }, "stderr": { "type": "string", "nullable": true, "description": "Standard error output from the code execution" }, "exitCode": { "type": "integer", "nullable": true, "description": "Exit code of the executed process" }, "killed": { "type": "boolean", "description": "Whether the process was killed due to timeout" }, "error": { "type": "string", "nullable": true, "description": "Error message if the code raised an exception" } } } } } }, "400": { "description": "Invalid job ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Invalid job ID format." } } } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Payment required to access this resource." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Forbidden." } } } } } }, "404": { "description": "Scrape job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Job not found." } } } } } }, "409": { "description": "Scrape replay context is unavailable or session could not be initialized", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Replay context is unavailable for this scrape job. Please rerun the scrape." } } } } } }, "410": { "description": "Scrape browser session has already been destroyed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Browser session has been destroyed." } } } } } }, "429": { "description": "Too many active browser sessions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "You have reached the maximum number of active browser sessions." } } } } } }, "502": { "description": "Failed to communicate with browser service", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Failed to execute code in browser session." } } } } } } } }, "delete": { "summary": "Stop the interactive browser session associated with a scrape job", "operationId": "stopInteractiveScrapeBrowserSession", "tags": ["Scraping"], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The scrape job ID" } ], "responses": { "200": { "description": "Interactive scrape browser session stopped successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Forbidden." } } } } } }, "404": { "description": "Interactive scrape browser session not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Browser session not found." } } } } } } } } }, "/parse": { "post": { "summary": "Upload and parse a file", "operationId": "parseFile", "tags": ["Scraping"], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "The file bytes to parse. Supported extensions: .html, .htm, .pdf, .docx, .doc, .odt, .rtf, .xlsx, .xls." }, "options": { "$ref": "#/components/schemas/ParseOptions" } }, "required": ["file"] }, "encoding": { "options": { "contentType": "application/json" } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "string", "example": "BAD_REQUEST" }, "error": { "type": "string", "example": "Invalid multipart form-data request." } } } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment required to access this resource." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Request rate limit exceeded. Please wait and try again later." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "string", "example": "UNKNOWN_ERROR" }, "error": { "type": "string", "example": "An unexpected error occurred on the server." } } } } } } } } }, "/batch/scrape": { "post": { "summary": "Scrape multiple URLs and optionally extract information using an LLM", "operationId": "scrapeAndExtractFromUrls", "tags": ["Scraping"], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string", "format": "uri", "description": "The URL to scrape" } }, "webhook": { "type": "object", "description": "A webhook specification object.", "properties": { "url": { "type": "string", "description": "The URL to send the webhook to. This will trigger for batch scrape started (batch_scrape.started), every page scraped (batch_scrape.page) and when the batch scrape is completed (batch_scrape.completed or batch_scrape.failed). The response will be the same as the `/scrape` endpoint." }, "headers": { "type": "object", "description": "Headers to send to the webhook URL.", "additionalProperties": { "type": "string" } }, "metadata": { "type": "object", "description": "Custom metadata that will be included in all webhook payloads for this crawl", "additionalProperties": true }, "events": { "type": "array", "description": "Type of events that should be sent to the webhook URL. (default: all)", "items": { "type": "string", "enum": ["completed", "page", "failed", "started"] } } }, "required": ["url"] }, "maxConcurrency": { "type": "integer", "description": "Maximum number of concurrent scrapes. This parameter allows you to set a concurrency limit for this batch scrape. If not specified, the batch scrape adheres to your team's concurrency limit." }, "ignoreInvalidURLs": { "type": "boolean", "default": true, "description": "If invalid URLs are specified in the urls array, they will be ignored. Instead of them failing the entire request, a batch scrape using the remaining valid URLs will be created, and the invalid URLs will be returned in the invalidURLs field of the response." } }, "required": ["urls"] }, { "$ref": "#/components/schemas/ScrapeOptions" }, { "type": "object", "properties": { "zeroDataRetention": { "type": "boolean", "default": false, "description": "If true, this will enable zero data retention for this batch scrape. To enable this feature, please contact help@firecrawl.dev" } } } ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchScrapeResponseObj" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment required to access this resource." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Request rate limit exceeded. Please wait and try again later." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred on the server." } } } } } } } } }, "/batch/scrape/{id}": { "parameters": [ { "name": "id", "in": "path", "description": "The ID of the batch scrape job", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Get the status of a batch scrape job", "operationId": "getBatchScrapeStatus", "tags": ["Scraping"], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchScrapeStatusResponseObj" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment required to access this resource." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Request rate limit exceeded. Please wait and try again later." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred on the server." } } } } } } } }, "delete": { "summary": "Cancel a batch scrape job", "operationId": "cancelBatchScrape", "tags": ["Scraping"], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful cancellation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["cancelled"], "example": "cancelled" } } } } } }, "404": { "description": "Batch scrape job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Batch scrape job not found." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred on the server." } } } } } } } } }, "/batch/scrape/{id}/errors": { "parameters": [ { "name": "id", "in": "path", "description": "The ID of the batch scrape job", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Get the errors of a batch scrape job", "operationId": "getBatchScrapeErrors", "tags": ["Scraping"], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlErrorsResponseObj" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment required to access this resource." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Request rate limit exceeded. Please wait and try again later." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred on the server." } } } } } } } } }, "/crawl/{id}": { "parameters": [ { "name": "id", "in": "path", "description": "The ID of the crawl job", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Get the status of a crawl job", "operationId": "getCrawlStatus", "tags": ["Crawling"], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlStatusResponseObj" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment required to access this resource." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Request rate limit exceeded. Please wait and try again later." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred on the server." } } } } } } } }, "delete": { "summary": "Cancel a crawl job", "operationId": "cancelCrawl", "tags": ["Crawling"], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful cancellation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["cancelled"], "example": "cancelled" } } } } } }, "404": { "description": "Crawl job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Crawl job not found." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred on the server." } } } } } } } } }, "/crawl/{id}/errors": { "parameters": [ { "name": "id", "in": "path", "description": "The ID of the crawl job", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Get the errors of a crawl job", "operationId": "getCrawlErrors", "tags": ["Crawling"], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlErrorsResponseObj" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment required to access this resource." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Request rate limit exceeded. Please wait and try again later." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred on the server." } } } } } } } } }, "/crawl": { "post": { "summary": "Crawl multiple URLs based on options", "operationId": "crawlUrls", "tags": ["Crawling"], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The base URL to start crawling from" }, "prompt": { "type": "string", "description": "A prompt to use to generate the crawler options (all the parameters below) from natural language. Explicitly set parameters will override the generated equivalents." }, "excludePaths": { "type": "array", "items": { "type": "string" }, "description": "URL pathname regex patterns that exclude matching URLs from the crawl. For example, if you set \"excludePaths\": [\"blog/.*\"] for the base URL firecrawl.dev, any results matching that pattern will be excluded, such as https://www.firecrawl.dev/blog/firecrawl-launch-week-1-recap." }, "includePaths": { "type": "array", "items": { "type": "string" }, "description": "URL pathname regex patterns that include matching URLs in the crawl. Only the paths that match the specified patterns will be included in the response. Note: the starting URL is also checked against these patterns — if it does not match, the crawl may return 0 pages. For example, if you set \"includePaths\": [\"blog/.*\"] for the base URL firecrawl.dev/blog, only pages under /blog/ will be included in the results, such as https://www.firecrawl.dev/blog/firecrawl-launch-week-1-recap." }, "maxDiscoveryDepth": { "type": "integer", "description": "Maximum depth to crawl based on discovery order. The root site and sitemapped pages has a discovery depth of 0. For example, if you set it to 1, and you set `sitemap: 'skip'`, you will only crawl the entered URL and all URLs that are linked on that page." }, "sitemap": { "type": "string", "enum": ["skip", "include", "only"], "description": "Sitemap mode when crawling. If you set it to 'skip', the crawler will ignore the website sitemap and only crawl the entered URL and discover pages from there onwards. If you set it to 'only', the crawler will only crawl URLs from the sitemap (plus the start URL) and will not discover links from HTML.", "default": "include" }, "ignoreQueryParameters": { "type": "boolean", "description": "Do not re-scrape the same path with different (or none) query parameters", "default": false }, "regexOnFullURL": { "type": "boolean", "description": "When true, includePaths and excludePaths regex patterns are matched against the full URL (including query parameters) instead of just the URL pathname. Useful when you need to filter URLs based on query strings.", "default": false }, "limit": { "type": "integer", "description": "Maximum number of pages to crawl. Default limit is 10000.", "default": 10000 }, "crawlEntireDomain": { "type": "boolean", "description": "Allows the crawler to follow internal links to sibling or parent URLs, not just child paths.\n\nfalse: Only crawls deeper (child) URLs.\n→ e.g. /features/feature-1 → /features/feature-1/tips ✅\n→ Won't follow /pricing or / ❌\n\ntrue: Crawls any internal links, including siblings and parents.\n→ e.g. /features/feature-1 → /pricing, /, etc. ✅\n\nUse true for broader internal coverage beyond nested paths.", "default": false }, "allowExternalLinks": { "type": "boolean", "description": "Allows the crawler to follow links to external websites.", "default": false }, "allowSubdomains": { "type": "boolean", "description": "Allows the crawler to follow links to subdomains of the main domain.", "default": false }, "ignoreRobotsTxt": { "type": "boolean", "description": "Ignore the website's robots.txt rules. Enterprise only — contact support@firecrawl.com to enable.", "default": false }, "robotsUserAgent": { "type": "string", "description": "Custom User-Agent string for robots.txt evaluation. When set, robots.txt is fetched with this User-Agent and allow/disallow rules are matched against it instead of the default. Enterprise only — contact support@firecrawl.com to enable." }, "delay": { "type": "number", "description": "Delay in seconds between scrapes. This helps respect website rate limits. Setting this forces concurrency to 1." }, "maxConcurrency": { "type": "integer", "description": "Maximum number of concurrent scrapes. This parameter allows you to set a concurrency limit for this crawl. If not specified, the crawl adheres to your team's concurrency limit." }, "webhook": { "type": "object", "description": "A webhook specification object.", "properties": { "url": { "type": "string", "description": "The URL to send the webhook to. This will trigger for crawl started (crawl.started), every page crawled (crawl.page) and when the crawl is completed (crawl.completed or crawl.failed). The response will be the same as the `/scrape` endpoint." }, "headers": { "type": "object", "description": "Headers to send to the webhook URL.", "additionalProperties": { "type": "string" } }, "metadata": { "type": "object", "description": "Custom metadata that will be included in all webhook payloads for this crawl", "additionalProperties": true }, "events": { "type": "array", "description": "Type of events that should be sent to the webhook URL. (default: all)", "items": { "type": "string", "enum": ["completed", "page", "failed", "started"] } } }, "required": ["url"] }, "scrapeOptions": { "$ref": "#/components/schemas/ScrapeOptions" }, "zeroDataRetention": { "type": "boolean", "default": false, "description": "If true, this will enable zero data retention for this crawl. To enable this feature, please contact help@firecrawl.dev" } }, "required": ["url"] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrawlResponse" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment required to access this resource." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Request rate limit exceeded. Please wait and try again later." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred on the server." } } } } } } } } }, "/crawl/params-preview": { "post": { "summary": "Preview crawl parameters generated from natural language prompt", "operationId": "crawlParamsPreview", "tags": ["Crawling"], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The URL to crawl" }, "prompt": { "type": "string", "maxLength": 10000, "description": "Natural language prompt describing what you want to crawl" } }, "required": ["url", "prompt"] } } } }, "responses": { "200": { "description": "Successful response with generated crawl parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The URL to crawl" }, "includePaths": { "type": "array", "items": { "type": "string" }, "description": "URL patterns to include" }, "excludePaths": { "type": "array", "items": { "type": "string" }, "description": "URL patterns to exclude" }, "maxDepth": { "type": "integer", "description": "Maximum crawl depth" }, "maxDiscoveryDepth": { "type": "integer", "description": "Maximum discovery depth" }, "crawlEntireDomain": { "type": "boolean", "description": "Whether to crawl the entire domain" }, "allowExternalLinks": { "type": "boolean", "description": "Whether to allow external links" }, "allowSubdomains": { "type": "boolean", "description": "Whether to allow subdomains" }, "sitemap": { "type": "string", "enum": ["skip", "include"], "description": "Sitemap handling strategy" }, "ignoreQueryParameters": { "type": "boolean", "description": "Whether to ignore query parameters" }, "ignoreRobotsTxt": { "type": "boolean", "description": "Whether robots.txt rules are ignored" }, "robotsUserAgent": { "type": "string", "description": "Custom User-Agent string used for robots.txt evaluation" }, "deduplicateSimilarURLs": { "type": "boolean", "description": "Whether to deduplicate similar URLs" }, "delay": { "type": "number", "description": "Delay between requests in milliseconds" }, "limit": { "type": "integer", "description": "Maximum number of pages to crawl" } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Invalid request parameters" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Unauthorized" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Failed to process natural language prompt" } } } } } } } } }, "/map": { "post": { "summary": "Map multiple URLs based on options", "operationId": "mapUrls", "tags": ["Mapping"], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The base URL to start crawling from" }, "search": { "type": "string", "description": "Specify a search query to order the results by relevance. Example: 'blog' will return URLs that contain the word 'blog' in the URL ordered by relevance." }, "sitemap": { "type": "string", "enum": ["skip", "include", "only"], "description": "Sitemap mode when mapping. If you set it to `skip`, the sitemap won't be used to find URLs. If you set it to `only`, only URLs that are in the sitemap will be returned. By default (`include`), the sitemap and other methods will be used together to find URLs.", "default": "include" }, "includeSubdomains": { "type": "boolean", "description": "Include subdomains of the website", "default": true }, "ignoreQueryParameters": { "type": "boolean", "description": "Do not return URLs with query parameters", "default": true }, "ignoreCache": { "type": "boolean", "description": "Bypass the sitemap cache to retrieve fresh URLs. Sitemap data is cached for up to 7 days; use this parameter when your sitemap has been recently updated.", "default": false }, "limit": { "type": "integer", "description": "Maximum number of links to return", "default": 5000, "maximum": 100000 }, "timeout": { "type": "integer", "description": "Timeout in milliseconds. There is no timeout by default." }, "location": { "type": "object", "description": "Location settings for the request. When specified, this will use an appropriate proxy if available and emulate the corresponding language and timezone settings. Defaults to 'US' if not specified.", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code (e.g., 'US', 'AU', 'DE', 'JP')", "pattern": "^[A-Z]{2}$", "default": "US" }, "languages": { "type": "array", "description": "Preferred languages and locales for the request in order of priority. Defaults to the language of the specified location. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language", "items": { "type": "string", "example": "en-US" } } } } }, "required": ["url"] }, "examples": { "example1": { "summary": "Example 1", "value": { "url": "", "search": "", "sitemap": "include", "includeSubdomains": true, "ignoreQueryParameters": true, "ignoreCache": false, "limit": 5000, "location": { "country": "US", "languages": ["en-US"] }, "timeout": 60000 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapResponse" } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment required to access this resource." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Request rate limit exceeded. Please wait and try again later." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred on the server." } } } } } } } } }, "/extract": { "post": { "summary": "Extract structured data from pages using LLMs", "operationId": "extractData", "tags": ["Extraction"], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string", "format": "uri", "description": "The URLs to extract data from. URLs should be in glob format." } }, "prompt": { "type": "string", "description": "Prompt to guide the extraction process" }, "schema": { "type": "object", "description": "Schema to define the structure of the extracted data. Must conform to [JSON Schema](https://json-schema.org/)." }, "enableWebSearch": { "type": "boolean", "description": "When true, the extraction will use web search to find additional data", "default": false }, "ignoreSitemap": { "type": "boolean", "description": "When true, sitemap.xml files will be ignored during website scanning", "default": false }, "includeSubdomains": { "type": "boolean", "description": "When true, subdomains of the provided URLs will also be scanned", "default": true }, "showSources": { "type": "boolean", "description": "When true, the sources used to extract the data will be included in the response as `sources` key", "default": false }, "scrapeOptions": { "$ref": "#/components/schemas/ScrapeOptions" }, "ignoreInvalidURLs": { "type": "boolean", "default": true, "description": "If invalid URLs are specified in the urls array, they will be ignored. Instead of them failing the entire request, an extract using the remaining valid URLs will be performed, and the invalid URLs will be returned in the invalidURLs field of the response." } }, "required": ["urls"] } } } }, "responses": { "200": { "description": "Successful extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid input data." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "An unexpected error occurred on the server." } } } } } } } } }, "/extract/{id}": { "parameters": [ { "name": "id", "in": "path", "description": "The ID of the extract job", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Get the status of an extract job", "operationId": "getExtractStatus", "tags": ["Extraction"], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractStatusResponse" } } } } } } }, "/agent": { "post": { "summary": "Start an agent task for agentic data extraction", "operationId": "startAgent", "tags": ["Agent"], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Optional list of URLs to constrain the agent to" }, "prompt": { "type": "string", "description": "The prompt describing what data to extract", "maxLength": 10000 }, "schema": { "type": "object", "description": "Optional JSON schema to structure the extracted data" }, "maxCredits": { "type": "number", "description": "Maximum credits to spend on this agent task. Defaults to 2500 if not set. Values above 2,500 are always billed as paid requests." }, "strictConstrainToURLs": { "type": "boolean", "description": "If true, agent will only visit URLs provided in the urls array" }, "model": { "type": "string", "enum": ["spark-1-mini", "spark-1-pro"], "default": "spark-1-mini", "description": "The model to use for the agent task. spark-1-mini (default) is 60% cheaper, spark-1-pro offers higher accuracy for complex tasks" } }, "required": ["prompt"] } } } }, "responses": { "200": { "description": "Agent task started successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" } } } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment required to access this resource." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Rate limit exceeded." } } } } } } } } }, "/agent/{jobId}": { "parameters": [ { "name": "jobId", "in": "path", "description": "The ID of the agent job", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Get the status of an agent job", "operationId": "getAgentStatus", "tags": ["Agent"], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string", "enum": ["processing", "completed", "failed"] }, "data": { "type": "object", "description": "The extracted data (only present when status is completed)" }, "model": { "type": "string", "enum": ["spark-1-pro", "spark-1-mini"], "default": "spark-1-pro", "description": "Model preset used for the agent run" }, "error": { "type": "string", "description": "Error message (only present when status is failed)" }, "expiresAt": { "type": "string", "format": "date-time" }, "creditsUsed": { "type": "number" } } } } } } } }, "delete": { "summary": "Cancel an agent job", "operationId": "cancelAgent", "tags": ["Agent"], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Agent job cancelled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } } } } }, "/crawl/active": { "get": { "summary": "Get all active crawls for the authenticated team", "operationId": "getActiveCrawls", "tags": ["Crawling"], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "crawls": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier of the crawl" }, "teamId": { "type": "string", "description": "The ID of the team that owns the crawl" }, "url": { "type": "string", "format": "uri", "description": "The origin URL of the crawl" }, "options": { "type": "object", "description": "The crawler options used for this crawl", "properties": { "scrapeOptions": { "$ref": "#/components/schemas/ScrapeOptions" } } } }, "required": ["id", "teamId", "url", "status", "options"] } } }, "required": ["success", "data"] } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Payment required to access this resource." } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Request rate limit exceeded. Please wait and try again later." } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "An unexpected error occurred on the server." } } } } } } } } }, "/team/credit-usage": { "get": { "summary": "Get remaining credits for the authenticated team", "operationId": "getCreditUsage", "tags": ["Billing"], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "remainingCredits": { "type": "number", "description": "Number of credits remaining for the team", "example": 1000 }, "planCredits": { "type": "number", "description": "Number of credits in the plan. This does not include coupon credits, credit packs, or auto recharge credits.", "example": 500000 }, "billingPeriodStart": { "type": "string", "format": "date-time", "description": "Start date of the billing period. null if using the free plan", "example": "2025-01-01T00:00:00Z", "nullable": true }, "billingPeriodEnd": { "type": "string", "format": "date-time", "description": "End date of the billing period. null if using the free plan", "example": "2025-01-31T23:59:59Z", "nullable": true } } } } } } } }, "404": { "description": "Credit usage information not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Could not find credit usage information" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Internal server error while fetching credit usage" } } } } } } } } }, "/team/credit-usage/historical": { "get": { "summary": "Get historical credit usage for the authenticated team", "operationId": "getHistoricalCreditUsage", "tags": ["Billing"], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "byApiKey", "in": "query", "description": "Get historical credit usage by API key", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "periods": { "type": "array", "items": { "type": "object", "properties": { "startDate": { "type": "string", "format": "date-time", "description": "Start date of the billing period", "example": "2025-01-01T00:00:00Z" }, "endDate": { "type": "string", "format": "date-time", "description": "End date of the billing period", "example": "2025-01-31T23:59:59Z" }, "apiKey": { "type": "string", "description": "Name of the API key used for the billing period. null if byApiKey is false (default)", "nullable": true }, "totalCredits": { "type": "integer", "description": "Total number of credits used in the billing period", "example": 1000 } } } } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Internal server error while fetching historical credit usage" } } } } } } } } }, "/team/token-usage": { "get": { "summary": "Get remaining tokens for the authenticated team (Extract only)", "operationId": "getTokenUsage", "tags": ["Billing"], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "remainingTokens": { "type": "number", "description": "Number of tokens remaining for the team", "example": 1000 }, "planTokens": { "type": "number", "description": "Number of tokens in the plan. This does not include coupon tokens.", "example": 500000 }, "billingPeriodStart": { "type": "string", "format": "date-time", "description": "Start date of the billing period. null if using the free plan", "example": "2025-01-01T00:00:00Z", "nullable": true }, "billingPeriodEnd": { "type": "string", "format": "date-time", "description": "End date of the billing period. null if using the free plan", "example": "2025-01-31T23:59:59Z", "nullable": true } } } } } } } }, "404": { "description": "Token usage information not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Could not find token usage information" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Internal server error while fetching token usage" } } } } } } } } }, "/team/token-usage/historical": { "get": { "summary": "Get historical token usage for the authenticated team (Extract only)", "operationId": "getHistoricalTokenUsage", "tags": ["Billing"], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "byApiKey", "in": "query", "description": "Get historical token usage by API key", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "periods": { "type": "array", "items": { "type": "object", "properties": { "startDate": { "type": "string", "format": "date-time", "description": "Start date of the billing period", "example": "2025-01-01T00:00:00Z" }, "endDate": { "type": "string", "format": "date-time", "description": "End date of the billing period", "example": "2025-01-31T23:59:59Z" }, "apiKey": { "type": "string", "description": "Name of the API key used for the billing period. null if byApiKey is false (default)", "nullable": true }, "totalTokens": { "type": "integer", "description": "Total number of tokens used in the billing period", "example": 1000 } } } } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Internal server error while fetching historical token usage" } } } } } } } } }, "/team/queue-status": { "get": { "summary": "Metrics about your team's scrape queue", "operationId": "getQueueStatus", "tags": ["Miscellaneous"], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "jobsInQueue": { "type": "number", "description": "Number of jobs currently in your queue" }, "activeJobsInQueue": { "type": "number", "description": "Number of jobs currently active" }, "waitingJobsInQueue": { "type": "number", "description": "Number of jobs currently waiting" }, "maxConcurrency": { "type": "number", "description": "Maximum number of concurrent active jobs based on your plan" }, "mostRecentSuccess": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent successful job", "nullable": true } } } } } } } } }, "/team/activity": { "get": { "summary": "List recent API activity", "operationId": "getActivity", "description": "Lists your team's recent API activity from the last 24 hours. Returns metadata about each job including the job ID, which can be used with the corresponding GET endpoint (e.g. GET /crawl/{id}) to retrieve full results. Supports cursor-based pagination and filtering by endpoint.", "tags": ["Account"], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "endpoint", "in": "query", "required": false, "schema": { "type": "string", "enum": ["scrape", "crawl", "batch_scrape", "search", "extract", "llmstxt", "deep_research", "map", "agent", "browser", "interact"] }, "description": "Filter by endpoint" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 }, "description": "Maximum number of results per page" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor for pagination. Use the cursor value from the previous response." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The job ID. Use this with the corresponding GET endpoint to retrieve results." }, "endpoint": { "type": "string", "enum": ["scrape", "crawl", "batch_scrape", "search", "extract", "llmstxt", "deep_research", "map", "agent", "browser", "interact"], "description": "The endpoint used for this job" }, "api_version": { "type": "string", "description": "The API version used for this request", "example": "v1" }, "created_at": { "type": "string", "format": "date-time", "description": "When the job was created" }, "target": { "type": "string", "nullable": true, "description": "The URL or query that was submitted" } } } }, "cursor": { "type": "string", "nullable": true, "description": "Cursor to use for the next page. Null if there are no more results." }, "has_more": { "type": "boolean", "description": "Whether there are more results available" } } } } } } } } }, "/search": { "post": { "summary": "Search and optionally scrape search results", "operationId": "searchAndScrape", "tags": ["Search"], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "The search query", "maxLength": 500 }, "limit": { "type": "integer", "description": "Maximum number of results to return (per source type when using multiple sources)", "default": 10, "maximum": 100, "minimum": 1 }, "sources": { "type": "array", "items": { "oneOf": [ { "type": "object", "title": "Web", "properties": { "type": { "type": "string", "enum": ["web"] }, "tbs": { "type": "string", "description": "Time-based search parameter. Supports predefined time ranges (`qdr:h`, `qdr:d`, `qdr:w`, `qdr:m`, `qdr:y`), custom date ranges (`cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY`), and sort by date (`sbd:1`). Values can be combined, e.g. `sbd:1,qdr:w`." }, "location": { "type": "string", "description": "Location parameter for search results" } }, "required": ["type"] }, { "type": "object", "title": "Images", "properties": { "type": { "type": "string", "enum": ["images"] } }, "required": ["type"] }, { "type": "object", "title": "News", "properties": { "type": { "type": "string", "enum": ["news"] } }, "required": ["type"] } ] }, "description": "Sources to search. Will determine the arrays available in the response. Defaults to ['web'].", "default": ["web"] }, "categories": { "type": "array", "items": { "oneOf": [ { "type": "object", "title": "GitHub", "properties": { "type": { "type": "string", "enum": ["github"] } }, "required": ["type"] }, { "type": "object", "title": "Research", "properties": { "type": { "type": "string", "enum": ["research"] } }, "required": ["type"] }, { "type": "object", "title": "PDF", "properties": { "type": { "type": "string", "enum": ["pdf"] } }, "required": ["type"] } ] }, "description": "Categories to filter results by. Defaults to [], which means results will not be filtered by any categories." }, "includeDomains": { "type": "array", "items": { "type": "string", "format": "hostname" }, "description": "Restricts search results to the specified domains. Domains should be hostnames only, without protocol or path. Cannot be used with excludeDomains." }, "excludeDomains": { "type": "array", "items": { "type": "string", "format": "hostname" }, "description": "Excludes search results from the specified domains. Domains should be hostnames only, without protocol or path. Cannot be used with includeDomains." }, "tbs": { "type": "string", "description": "Time-based search parameter. Supports predefined time ranges (`qdr:h`, `qdr:d`, `qdr:w`, `qdr:m`, `qdr:y`), custom date ranges (`cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY`), and sort by date (`sbd:1`). Values can be combined, e.g. `sbd:1,qdr:w`." }, "location": { "type": "string", "description": "Location parameter for search results (e.g. `San Francisco,California,United States`). For best results, set both this and the `country` parameter." }, "country": { "type": "string", "description": "ISO country code for geo-targeting search results (e.g. `US`). For best results, set both this and the `location` parameter.", "default": "US" }, "timeout": { "type": "integer", "description": "Timeout in milliseconds", "default": 60000 }, "ignoreInvalidURLs": { "type": "boolean", "description": "Excludes URLs from the search results that are invalid for other Firecrawl endpoints. This helps reduce errors if you are piping data from search into other Firecrawl API endpoints.", "default": false }, "enterprise": { "type": "array", "items": { "type": "string", "enum": ["anon", "zdr"] }, "description": "Enterprise search options for Zero Data Retention (ZDR). Use `[\"zdr\"]` for end-to-end ZDR (10 credits / 10 results) or `[\"anon\"]` for anonymized ZDR (2 credits / 10 results). Must be enabled for your team." }, "scrapeOptions": { "allOf": [ { "$ref": "#/components/schemas/ScrapeOptions" } ], "description": "Options for scraping search results", "default": {} } }, "required": ["query"] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "web": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Title from search result" }, "description": { "type": "string", "description": "Description from search result" }, "url": { "type": "string", "description": "URL of the search result" }, "markdown": { "type": "string", "nullable": true, "description": "Markdown content if scraping was requested" }, "html": { "type": "string", "nullable": true, "description": "HTML content if requested in formats" }, "rawHtml": { "type": "string", "nullable": true, "description": "Raw HTML content if requested in formats" }, "links": { "type": "array", "items": { "type": "string" }, "description": "Links found if requested in formats" }, "screenshot": { "type": "string", "nullable": true, "description": "Screenshot URL if requested in formats. Screenshots expire after 24 hours and can no longer be downloaded." }, "audio": { "type": "string", "nullable": true, "description": "Signed URL to the extracted MP3 audio file if `audio` is in `formats`. The signed URL expires after 1 hour." }, "video": { "type": "string", "nullable": true, "description": "Signed URL to the extracted video file if `video` is in `formats`. The signed URL expires after 1 hour." }, "metadata": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "sourceURL": { "type": "string", "description": "The original URL that was requested. May differ from the page's final URL if redirects occurred." }, "url": { "type": "string", "description": "The final URL of the page after all redirects have been followed." }, "statusCode": { "type": "integer" }, "error": { "type": "string", "nullable": true } } } } } }, "images": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Title from search result" }, "imageUrl": { "type": "string", "description": "URL of the image" }, "imageWidth": { "type": "integer", "description": "Width of the image" }, "imageHeight": { "type": "integer", "description": "Height of the image" }, "url": { "type": "string", "description": "URL of the search result" }, "position": { "type": "integer", "description": "Position of the search result" } } } }, "news": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the article" }, "snippet": { "type": "string", "description": "Snippet from the article" }, "url": { "type": "string", "description": "URL of the article" }, "date": { "type": "string", "description": "Date of the article" }, "imageUrl": { "type": "string", "description": "Image URL of the article" }, "position": { "type": "integer", "description": "Position of the article" }, "markdown": { "type": "string", "nullable": true, "description": "Markdown content if scraping was requested" }, "html": { "type": "string", "nullable": true, "description": "HTML content if requested in formats" }, "rawHtml": { "type": "string", "nullable": true, "description": "Raw HTML content if requested in formats" }, "links": { "type": "array", "items": { "type": "string" }, "description": "Links found if requested in formats" }, "screenshot": { "type": "string", "nullable": true, "description": "Screenshot URL if requested in formats. Screenshots expire after 24 hours and can no longer be downloaded." }, "audio": { "type": "string", "nullable": true, "description": "Signed URL to the extracted MP3 audio file if `audio` is in `formats`. The signed URL expires after 1 hour." }, "video": { "type": "string", "nullable": true, "description": "Signed URL to the extracted video file if `video` is in `formats`. The signed URL expires after 1 hour." }, "metadata": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "sourceURL": { "type": "string", "description": "The original URL that was requested. May differ from the page's final URL if redirects occurred." }, "url": { "type": "string", "description": "The final URL of the page after all redirects have been followed." }, "statusCode": { "type": "integer" }, "error": { "type": "string", "nullable": true } } } } } } }, "description": "The search results. The arrays available will depend on the sources you specified in the request. By default, the `web` array will be returned." }, "warning": { "type": "string", "nullable": true, "description": "Warning message if any issues occurred" }, "id": { "type": "string", "description": "The ID of the search job" }, "creditsUsed": { "type": "integer", "description": "The number of credits used for the search" } } } } } }, "408": { "description": "Request timeout", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "Request timed out" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "code": { "type": "string", "example": "UNKNOWN_ERROR" }, "error": { "type": "string", "example": "An unexpected error occurred on the server." } } } } } } } } }, "/browser": { "post": { "summary": "Create a browser session", "operationId": "createBrowserSession", "tags": ["Browser"], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ttl": { "type": "integer", "default": 300, "minimum": 30, "maximum": 3600, "description": "Total time-to-live in seconds for the browser session" }, "activityTtl": { "type": "integer", "minimum": 10, "maximum": 3600, "description": "Time in seconds before the session is destroyed due to inactivity" }, "streamWebView": { "type": "boolean", "default": true, "description": "Whether to stream a live view of the browser" }, "profile": { "type": "object", "description": "Enable persistent storage across browser sessions. Data saved in one session can be loaded in a later session using the same name.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "A name for the profile. Sessions with the same name share storage." }, "saveChanges": { "type": "boolean", "default": true, "description": "When true, browser state is saved back to the profile on close. Set to false to load existing data without writing. Multiple non-saving sessions are allowed but only one saving session at a time." } }, "required": ["name"] } } } } } }, "responses": { "200": { "description": "Browser session created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string", "description": "The unique session identifier" }, "cdpUrl": { "type": "string", "description": "WebSocket URL for Chrome DevTools Protocol access" }, "liveViewUrl": { "type": "string", "description": "URL to view the browser session in real time" }, "interactiveLiveViewUrl": { "type": "string", "description": "URL to interact with the browser session in real time (click, type, scroll)" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the session will expire based on TTL" } } } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment required to access this resource." } } } } } } } }, "get": { "summary": "List browser sessions", "operationId": "listBrowserSessions", "tags": ["Browser"], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": ["active", "destroyed"] }, "description": "Filter sessions by status" } ], "responses": { "200": { "description": "List of browser sessions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "sessions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": ["active", "destroyed"] }, "cdpUrl": { "type": "string" }, "liveViewUrl": { "type": "string" }, "interactiveLiveViewUrl": { "type": "string", "description": "URL to interact with the browser session in real time (click, type, scroll)" }, "streamWebView": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "lastActivity": { "type": "string", "format": "date-time" } } } } } } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment required to access this resource." } } } } } } } } }, "/browser/{sessionId}/execute": { "post": { "summary": "Execute code in a browser session", "operationId": "executeBrowserCode", "tags": ["Browser"], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The browser session ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["code"], "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "Code to execute in the browser sandbox" }, "language": { "type": "string", "enum": ["python", "node", "bash"], "default": "node", "description": "Language of the code to execute. Use `node` for JavaScript or `bash` for agent-browser CLI commands." }, "timeout": { "type": "integer", "minimum": 1, "maximum": 300, "description": "Execution timeout in seconds" } } } } } }, "responses": { "200": { "description": "Code executed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "stdout": { "type": "string", "nullable": true, "description": "Standard output from the code execution" }, "result": { "type": "string", "nullable": true, "description": "Standard output (alias for stdout)" }, "stderr": { "type": "string", "nullable": true, "description": "Standard error output from the code execution" }, "exitCode": { "type": "integer", "nullable": true, "description": "Exit code of the executed process" }, "killed": { "type": "boolean", "description": "Whether the process was killed due to timeout" }, "error": { "type": "string", "nullable": true, "description": "Error message if the code raised an exception" } } } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment required to access this resource." } } } } } } } } }, "/browser/{sessionId}": { "delete": { "summary": "Delete a browser session", "operationId": "deleteBrowserSession", "tags": ["Browser"], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The browser session ID" } ], "responses": { "200": { "description": "Browser session deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "sessionDurationMs": { "type": "integer", "description": "Total session duration in milliseconds" }, "creditsBilled": { "type": "number", "description": "Number of credits billed for the session" } } } } } }, "402": { "description": "Payment required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment required to access this resource." } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Formats": { "type": "array", "items": { "oneOf": [ { "type": "object", "title": "Markdown", "properties": { "type": { "type": "string", "enum": ["markdown"] } }, "required": ["type"] }, { "type": "object", "title": "Summary", "properties": { "type": { "type": "string", "enum": ["summary"] } }, "required": ["type"] }, { "type": "object", "title": "HTML", "properties": { "type": { "type": "string", "enum": ["html"] } }, "required": ["type"] }, { "type": "object", "title": "Raw HTML", "properties": { "type": { "type": "string", "enum": ["rawHtml"] } }, "required": ["type"] }, { "type": "object", "title": "Links", "properties": { "type": { "type": "string", "enum": ["links"] } }, "required": ["type"] }, { "type": "object", "title": "Images", "properties": { "type": { "type": "string", "enum": ["images"] } }, "required": ["type"] }, { "type": "object", "title": "Screenshot", "properties": { "type": { "type": "string", "enum": ["screenshot"] }, "fullPage": { "type": "boolean", "description": "Whether to capture a full-page screenshot (ignores viewport.height) or limit to the current viewport.", "default": false }, "quality": { "type": "integer", "description": "The quality of the screenshot, from 1 to 100. 100 is the highest quality." }, "viewport": { "type": "object", "properties": { "width": { "type": "integer", "description": "The width of the viewport in pixels" }, "height": { "type": "integer", "description": "The height of the viewport in pixels" } }, "required": ["width", "height"] } }, "required": ["type"] }, { "type": "object", "title": "JSON", "properties": { "type": { "type": "string", "enum": ["json"] }, "schema": { "type": "object", "description": "The schema to use for the JSON output. Must conform to [JSON Schema](https://json-schema.org/)." }, "prompt": { "type": "string", "description": "The prompt to use for the JSON output" } }, "required": ["type"] }, { "type": "object", "title": "Change Tracking", "properties": { "type": { "type": "string", "enum": ["changeTracking"] }, "modes": { "type": "array", "items": { "type": "string", "enum": ["git-diff", "json"] }, "description": "The mode to use for change tracking. 'git-diff' provides a detailed diff, and 'json' compares extracted JSON data." }, "schema": { "type": "object", "description": "Schema for JSON extraction when using 'json' mode. Defines the structure of data to extract and compare. Must conform to [JSON Schema](https://json-schema.org/)." }, "prompt": { "type": "string", "description": "Prompt to use for change tracking when using 'json' mode. If not provided, the default prompt will be used." }, "tag": { "type": "string", "nullable": true, "default": null, "description": "Tag to use for change tracking. Tags can separate change tracking history into separate \"branches\", where change tracking with a specific tagwill only compare to scrapes made in the same tag. If not provided, the default tag (null) will be used." } }, "required": ["type"] }, { "type": "object", "title": "Branding", "properties": { "type": { "type": "string", "enum": ["branding"] } }, "required": ["type"] }, { "type": "object", "title": "Audio", "description": "Extract audio (MP3) from supported video URLs, e.g. YouTube. Returns a signed GCS URL.", "properties": { "type": { "type": "string", "enum": ["audio"] } }, "required": ["type"] }, { "type": "object", "title": "Video", "description": "Extract best-quality video from supported video URLs, e.g. YouTube. Returns a signed GCS URL.", "properties": { "type": { "type": "string", "enum": ["video"] } }, "required": ["type"] }, { "type": "object", "title": "Question", "description": "Ask a natural-language question about the page. Returns the answer in the response `answer` field.", "properties": { "type": { "type": "string", "enum": ["question"] }, "question": { "type": "string", "maxLength": 10000, "description": "The question to answer about the page. Maximum 10,000 characters." } }, "required": ["type", "question"] }, { "type": "object", "title": "Highlights", "description": "Find relevant source text from the page. Returns the selected text in the response `highlights` field.", "properties": { "type": { "type": "string", "enum": ["highlights"] }, "query": { "type": "string", "maxLength": 10000, "description": "The text-selection query to run against the page. Maximum 10,000 characters." } }, "required": ["type", "query"] } ] }, "description": "Output formats to include in the response. You can specify one or more formats, either as strings (e.g., `'markdown'`) or as objects with additional options (e.g., `{ type: 'json', schema: {...} }`). Some formats require specific options to be set. Example: `['markdown', { type: 'json', schema: {...} }]`.", "default": ["markdown"] }, "ParseFormats": { "type": "array", "items": { "oneOf": [ { "type": "object", "title": "Markdown", "properties": { "type": { "type": "string", "enum": ["markdown"] } }, "required": ["type"] }, { "type": "object", "title": "Summary", "properties": { "type": { "type": "string", "enum": ["summary"] } }, "required": ["type"] }, { "type": "object", "title": "HTML", "properties": { "type": { "type": "string", "enum": ["html"] } }, "required": ["type"] }, { "type": "object", "title": "Raw HTML", "properties": { "type": { "type": "string", "enum": ["rawHtml"] } }, "required": ["type"] }, { "type": "object", "title": "Links", "properties": { "type": { "type": "string", "enum": ["links"] } }, "required": ["type"] }, { "type": "object", "title": "Images", "properties": { "type": { "type": "string", "enum": ["images"] } }, "required": ["type"] }, { "type": "object", "title": "JSON", "properties": { "type": { "type": "string", "enum": ["json"] }, "schema": { "type": "object", "description": "The schema to use for the JSON output. Must conform to [JSON Schema](https://json-schema.org/)." }, "prompt": { "type": "string", "description": "The prompt to use for the JSON output" } }, "required": ["type"] } ] }, "description": "Output formats supported for `/parse` uploads. Browser-rendering formats and change tracking are not supported.", "default": ["markdown"] }, "ParseOptions": { "type": "object", "description": "Optional parse options sent as JSON in the multipart `options` field.", "properties": { "formats": { "$ref": "#/components/schemas/ParseFormats" }, "onlyMainContent": { "type": "boolean", "description": "Only return the main content of the page excluding headers, navs, footers, etc.", "default": true }, "includeTags": { "type": "array", "items": { "type": "string" }, "description": "Tags to include in the output." }, "excludeTags": { "type": "array", "items": { "type": "string" }, "description": "Tags to exclude from the output." }, "headers": { "type": "object", "description": "Headers to send when additional network requests are required." }, "timeout": { "type": "integer", "description": "Timeout in milliseconds for the request. Default is 30000 (30 seconds). Maximum is 300000 (300 seconds).", "default": 30000, "maximum": 300000 }, "parsers": { "type": "array", "description": "Controls file parser behavior when relevant (for example PDF parser mode).", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["pdf"] }, "mode": { "type": "string", "enum": ["fast", "auto", "ocr"], "default": "auto", "description": "PDF parsing mode. \"fast\": text-only extraction. \"auto\": text-first with OCR fallback. \"ocr\": OCR on every page." }, "maxPages": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Maximum number of pages to parse from the PDF." } }, "required": ["type"], "additionalProperties": false } ] }, "default": ["pdf"] }, "skipTlsVerification": { "type": "boolean", "description": "Skip TLS certificate verification when making requests.", "default": true }, "removeBase64Images": { "type": "boolean", "description": "Remove base64-encoded images from output and keep alt text placeholders.", "default": true }, "blockAds": { "type": "boolean", "description": "Enable ad and cookie popup blocking.", "default": true }, "proxy": { "type": "string", "enum": ["basic", "auto"], "description": "Proxy mode for parse uploads. `/parse` supports only `basic` and `auto`." }, "origin": { "type": "string", "description": "Origin identifier for analytics and logging.", "default": "api" }, "integration": { "type": "string", "nullable": true, "description": "Optional integration identifier." }, "zeroDataRetention": { "type": "boolean", "default": false, "description": "If true, this will enable zero data retention for this parse. To enable this feature, please contact help@firecrawl.dev" } } }, "ScrapeOptions": { "type": "object", "properties": { "formats": { "$ref": "#/components/schemas/Formats" }, "onlyMainContent": { "type": "boolean", "description": "Only return the main content of the page excluding headers, navs, footers, etc. This is a deterministic HTML-level filter applied before markdown is generated; no LLM is involved.", "default": true }, "onlyCleanContent": { "type": "boolean", "description": "Beta. Run an additional LLM-based pass over the generated markdown to remove residual boilerplate that `onlyMainContent` can miss (cookie banners, ad blocks, social share widgets, breadcrumbs, newsletter signups, comment sections, related-article lists). Headings, lists, tables, code blocks, image references, and inline links are preserved. Can be combined with `onlyMainContent` (the most common setup) or used on its own. Skipped with a warning when the markdown exceeds the cleaning model's output token limit (the original markdown is preserved). Not supported on zero-data-retention requests.", "default": false }, "includeTags": { "type": "array", "items": { "type": "string" }, "description": "Tags to include in the output." }, "excludeTags": { "type": "array", "items": { "type": "string" }, "description": "Tags to exclude from the output." }, "maxAge": { "type": "integer", "description": "Returns a cached version of the page if it is younger than this age in milliseconds. If a cached version of the page is older than this value, the page will be scraped. If you do not need extremely fresh data, enabling this can speed up your scrapes by 500%. Defaults to 2 days.", "default": 172800000 }, "minAge": { "type": "integer", "description": "When set, the request only checks the cache and never triggers a fresh scrape. The value is in milliseconds and specifies the minimum age the cached data must be. If matching cached data exists, it is returned instantly. If no cached data is found, a 404 with error code SCRAPE_NO_CACHED_DATA is returned. Set to 1 to accept any cached data regardless of age." }, "headers": { "type": "object", "description": "Headers to send with the request. Can be used to send cookies, user-agent, etc." }, "waitFor": { "type": "integer", "description": "Specify a delay in milliseconds before fetching the content, allowing the page sufficient time to load. This waiting time is in addition to Firecrawl's smart wait feature.", "default": 0 }, "mobile": { "type": "boolean", "description": "Set to true if you want to emulate scraping from a mobile device. Useful for testing responsive pages and taking mobile screenshots.", "default": false }, "skipTlsVerification": { "type": "boolean", "description": "Skip TLS certificate verification when making requests.", "default": true }, "timeout": { "type": "integer", "description": "Timeout in milliseconds for the request. Minimum is 1000 (1 second). Default is 60000 (60 seconds). Maximum is 300000 (300 seconds).", "default": 60000, "minimum": 1000, "maximum": 300000 }, "parsers": { "type": "array", "description": "Controls how files are processed during scraping. When \"pdf\" is included (default), the PDF content is extracted and converted to markdown format, with billing based on the number of pages (1 credit per page). When an empty array is passed, the PDF file is returned in base64 encoding with a flat rate of 1 credit for the entire PDF.", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": ["pdf"] }, "mode": { "type": "string", "enum": ["fast", "auto", "ocr"], "default": "auto", "description": "PDF parsing mode. \"fast\": text-based extraction only (embedded text, fastest). \"auto\" (default): attempts fast extraction first, falls back to OCR if needed. \"ocr\": forces OCR parsing on every page." }, "maxPages": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Maximum number of pages to parse from the PDF. Must be a positive integer up to 10000." } }, "required": ["type"], "additionalProperties": false } ] }, "default": ["pdf"] }, "actions": { "type": "array", "description": "Actions to perform on the page before grabbing the content", "items": { "oneOf": [ { "title": "Wait", "oneOf": [ { "type": "object", "title": "Wait by Duration", "properties": { "type": { "type": "string", "enum": ["wait"], "description": "Wait for a specified amount of milliseconds" }, "milliseconds": { "type": "integer", "minimum": 1, "description": "Number of milliseconds to wait" } }, "required": ["type", "milliseconds"], "additionalProperties": false }, { "type": "object", "title": "Wait for Element", "properties": { "type": { "type": "string", "enum": ["wait"], "description": "Wait for a specific element to appear" }, "selector": { "type": "string", "description": "CSS selector to wait for", "example": "#my-element" } }, "required": ["type", "selector"], "additionalProperties": false } ] }, { "type": "object", "title": "Screenshot", "properties": { "type": { "type": "string", "enum": ["screenshot"], "description": "Take a screenshot. The links will be in the response's `actions.screenshots` array." }, "fullPage": { "type": "boolean", "description": "Whether to capture a full-page screenshot (ignores viewport.height) or limit to the current viewport.", "default": false }, "quality": { "type": "integer", "description": "The quality of the screenshot, from 1 to 100. 100 is the highest quality." }, "viewport": { "type": "object", "properties": { "width": { "type": "integer", "description": "The width of the viewport in pixels" }, "height": { "type": "integer", "description": "The height of the viewport in pixels" } }, "required": ["width", "height"] } }, "required": ["type"] }, { "type": "object", "title": "Click", "properties": { "type": { "type": "string", "enum": ["click"], "description": "Click on an element" }, "selector": { "type": "string", "description": "Query selector to find the element by", "example": "#load-more-button" }, "all": { "type": "boolean", "description": "Clicks all elements matched by the selector, not just the first one. Does not throw an error if no elements match the selector.", "default": false } }, "required": ["type", "selector"] }, { "type": "object", "title": "Write text", "properties": { "type": { "type": "string", "enum": ["write"], "description": "Write text into an input field, text area, or contenteditable element. Note: You must first focus the element using a 'click' action before writing. The text will be typed character by character to simulate keyboard input." }, "text": { "type": "string", "description": "Text to type", "example": "Hello, world!" } }, "required": ["type", "text"] }, { "type": "object", "title": "Press a key", "description": "Press a key on the page. See https://asawicki.info/nosense/doc/devices/keyboard/key_codes.html for key codes.", "properties": { "type": { "type": "string", "enum": ["press"], "description": "Press a key on the page" }, "key": { "type": "string", "description": "Key to press", "example": "Enter" } }, "required": ["type", "key"] }, { "type": "object", "title": "Scroll", "properties": { "type": { "type": "string", "enum": ["scroll"], "description": "Scroll the page or a specific element" }, "direction": { "type": "string", "enum": ["up", "down"], "description": "Direction to scroll", "default": "down" }, "selector": { "type": "string", "description": "Query selector for the element to scroll", "example": "#my-element" } }, "required": ["type"] }, { "type": "object", "title": "Scrape", "properties": { "type": { "type": "string", "enum": ["scrape"], "description": "Scrape the current page content, returns the url and the html." } }, "required": ["type"] }, { "type": "object", "title": "Execute JavaScript", "properties": { "type": { "type": "string", "enum": ["executeJavascript"], "description": "Execute JavaScript code on the page" }, "script": { "type": "string", "description": "JavaScript code to execute", "example": "document.querySelector('.button').click();" } }, "required": ["type", "script"] }, { "type": "object", "title": "Generate PDF", "properties": { "type": { "type": "string", "enum": ["pdf"], "description": "Generate a PDF of the current page. The PDF will be returned in the `actions.pdfs` array of the response." }, "format": { "type": "string", "enum": [ "A0", "A1", "A2", "A3", "A4", "A5", "A6", "Letter", "Legal", "Tabloid", "Ledger" ], "description": "The page size of the resulting PDF", "default": "Letter" }, "landscape": { "type": "boolean", "description": "Whether to generate the PDF in landscape orientation", "default": false }, "scale": { "type": "number", "description": "The scale multiplier of the resulting PDF", "default": 1 } }, "required": ["type"] } ] } }, "location": { "type": "object", "description": "Location settings for the request. When specified, this will use an appropriate proxy if available and emulate the corresponding language and timezone settings. Defaults to 'US' if not specified.", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code (e.g., 'US', 'AU', 'DE', 'JP')", "pattern": "^[A-Z]{2}$", "default": "US" }, "languages": { "type": "array", "description": "Preferred languages and locales for the request in order of priority. Defaults to the language of the specified location. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language", "items": { "type": "string", "example": "en-US" } } } }, "removeBase64Images": { "type": "boolean", "description": "Removes all base 64 images from the markdown output, which may be overwhelmingly long. This does not affect html or rawHtml formats. The image's alt text remains in the output, but the URL is replaced with a placeholder.", "default": true }, "blockAds": { "type": "boolean", "description": "Enables ad-blocking and cookie popup blocking.", "default": true }, "proxy": { "type": "string", "enum": ["basic", "enhanced", "auto"], "description": "Specifies the type of proxy to use.\n\n - **basic**: Proxies for scraping sites with none to basic anti-bot solutions. Fast and usually works.\n - **enhanced**: Enhanced proxies for scraping sites with advanced anti-bot solutions. Slower, but more reliable on certain sites. Costs up to 5 credits per request.\n - **auto**: Firecrawl will automatically retry scraping with enhanced proxies if the basic proxy fails. If the retry with enhanced is successful, 5 credits will be billed for the scrape. If the first attempt with basic is successful, only the regular cost will be billed.", "default": "auto" }, "storeInCache": { "type": "boolean", "description": "If true, the page will be stored in the Firecrawl index and cache. Setting this to false is useful if your scraping activity may have data protection concerns. Using some parameters associated with sensitive scraping (e.g. actions, headers) will force this parameter to be false.", "default": true }, "lockdown": { "type": "boolean", "description": "If true, serves the request from Firecrawl's cache only and never makes an outbound request to the target URL. Designed for compliance-constrained or air-gapped environments where the scrape request itself could leak sensitive information. On cache miss, returns a 404 with error code SCRAPE_LOCKDOWN_CACHE_MISS (the URL is never logged on miss). Lockdown requests are treated as zero data retention. Default maxAge is extended to 2 years so existing cached pages remain eligible. Billed at 5 credits on hit, 1 credit on cache miss.", "default": false }, "profile": { "type": "object", "description": "Enable persistent browser storage across scrape and interact sessions. Pass a profile when scraping to preserve cookies, localStorage, and session data. Sessions with the same profile name share browser state.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "description": "A name for the profile. Scrapes with the same name share browser state (cookies, localStorage, sessions)." }, "saveChanges": { "type": "boolean", "default": true, "description": "When true, browser state is saved back to the profile when the interact session stops. Set to false to load existing data without writing. Only one saving session is allowed at a time." } }, "required": ["name"] } } }, "ScrapeResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "markdown": { "type": "string" }, "summary": { "type": "string", "nullable": true, "description": "Summary of the page if `summary` is in `formats`" }, "html": { "type": "string", "nullable": true, "description": "Cleaned HTML of the page if `html` is in `formats`. Removes `