Firecrawl Scraping API
The Scraping API from Firecrawl — 6 operation(s) for scraping.
OpenAPI Specification
openapi: 3.0.0
info:
title: Firecrawl Account Scraping 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
security:
- bearerAuth: []
tags:
- name: Scraping
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:
success:
type: boolean
example: true
message:
type: string
example: Batch scrape job successfully 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.
components:
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
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
BatchScrapeStatusResponseObj:
type: object
properties:
status:
type: string
description: The current status of the batch scrape. Can be `scraping`, `completed`, or `failed`.
total:
type: integer
description: The total number of pages that were attempted to be scraped.
completed:
type: integer
description: The number of pages that have been successfully scraped.
creditsUsed:
type: integer
description: The number of credits used for the batch scrape.
expiresAt:
type: string
format: date-time
description: The date and time when the batch scrape will expire.
next:
type: string
nullable: true
description: The URL to retrieve the next 10MB of data. Returned if the batch scrape is not completed or if the response is larger than 10MB.
data:
type: array
description: The data of the batch scrape.
items:
type: object
properties:
markdown:
type: string
html:
type: string
nullable: true
description: HTML version of the content on page if `includeHtml` is true
rawHtml:
type: string
nullable: true
description: Raw HTML content of the page if `includeRawHtml` is true
links:
type: array
items:
type: string
description: List of links on the page if `includeLinks` is true
screenshot:
type: string
nullable: true
description: Screenshot of the page if `includeScreenshot` is true
metadata:
type: object
properties:
title:
oneOf:
- type: string
- type: array
items:
type: string
description: Title extracted from the page, can be a string or array of strings
description:
oneOf:
- type: string
- type: array
items:
type: string
description: Description extracted from the page, can be a string or array of strings
language:
oneOf:
- type: string
- type: array
items:
type: string
nullable: true
description: Language extracted from the page, can be a string or array of strings
sourceURL:
type: string
format: uri
description: The original URL that was requested. May differ from the page's final URL if redirects occurred.
url:
type: string
format: uri
description: The final URL of the page after all redirects have been followed.
keywords:
oneOf:
- type: string
- type: array
items:
type: string
description: Keywords extracted from the page, can be a string or array of strings
ogLocaleAlternate:
type: array
items:
type: string
description: Alternative locales for the page
'<any other metadata> ':
type: string
statusCode:
type: integer
description: The status code of the page
error:
type: string
nullable: true
description: The error message of the page
concurrencyLimited:
type: boolean
description: Whether this scrape was throttled due to team concurrency limits
concurrencyQueueDurationMs:
type: number
description: Time in milliseconds the request waited in the concurrency queue. Only present when concurrency
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/firecrawl/refs/heads/main/openapi/firecrawl-scraping-api-openapi.yml