Rust Agent Quickstart

Canonical Firecrawl Rust quickstart for external agents using search, scrape, and interact.

Canonical Firecrawl Rust quickstart for agents. Generated from SDK source (firecrawl crate v2.18.0) and the v2 OpenAPI spec.

Install

cargo add firecrawl

Authenticate

use firecrawl::Client;

let client = Client::new("fc-your-api-key")?;
// Self-hosted:
// let client = Client::new_selfhosted("http://localhost:3002", Some("fc-your-api-key"))?;

When To Use What

• search: use when you start with a query and need discovery.
• scrape: use when you already have a URL and want page content.
• interact: use when the page needs clicks, forms, or post-scrape browser actions. Requires a scrape job ID from a prior scrape.

Search

Why use it

Discover relevant pages from a query, then pick URLs to scrape or interact with. Constrain results to a site with site: in the query string.

Preferred SDK method

client.search(query, options) → Result<SearchResponse, FirecrawlError>

Example

use firecrawl::{Client, SearchOptions, SearchSource, ScrapeOptions, Format};

let options = SearchOptions {
    sources: Some(vec![SearchSource::Web, SearchSource::News]),
    limit: Some(10),
    scrape_options: Some(ScrapeOptions {
        formats: Some(vec![Format::Markdown]),
        only_main_content: Some(true),
        ..Default::default()
    }),
    ..Default::default()
};

let results = client
    .search("site:docs.firecrawl.dev webhook retries", options)
    .await?;

// Results in results.data.web, results.data.news, results.data.images

A convenience helper client.search_and_scrape(query, limit) returns Vec<Document> directly.

Parameters

Parameter	Type	Description
query	impl AsRef<str>	Search query. Use site:example.com to scope to a domain.
options.sources	Vec<SearchSource>	Sources: Web, News, Images.
options.categories	Vec<SearchCategory>	Filter results: Github, Research, Pdf.
options.include_domains	Vec<String>	Restrict results to these domains.
options.exclude_domains	Vec<String>	Exclude results from these domains.
options.limit	u32	Max results. Default: 5, max: 20.
options.tbs	String	Time-based filter (e.g. qdr:d, qdr:w).
options.location	String	Location string for localized results.
options.ignore_invalid_urls	bool	Drop URLs that cannot be scraped.
options.timeout	u32	Request timeout in milliseconds.
options.highlights	bool	Generate query-relevant highlights. Defaults to true.
options.scrape_options	ScrapeOptions	Scrape each search result (see Scrape parameters).

Scrape

Why use it

Get structured content from a URL in one or more formats.

Preferred SDK method

client.scrape(url, options) → Result<Document, FirecrawlError>

Example

use firecrawl::{Client, ScrapeOptions, Format, JsonOptions};

let doc = client
    .scrape("https://example.com/pricing", ScrapeOptions {
        formats: Some(vec![Format::Markdown, Format::Links, Format::Json]),
        json_options: Some(JsonOptions {
            prompt: Some("Extract plan names and prices.".to_string()),
            ..Default::default()
        }),
        only_main_content: Some(true),
        wait_for: Some(1000),
        ..Default::default()
    })
    .await?;

Parameters

Parameter	Type	Description
url	impl AsRef<str>	The URL to scrape.
options.formats	Vec<Format>	Output formats: Markdown, Html, RawHtml, Links, Images, Screenshot, Summary, ChangeTracking, Json, Attributes, Branding, Product, Menu, Audio, Video, Question(QuestionFormat), Highlights(HighlightsFormat).
options.headers	HashMap<String, String>	Custom HTTP headers.
options.include_tags	Vec<String>	Only include content from these HTML tags.
options.exclude_tags	Vec<String>	Exclude content from these HTML tags.
options.only_main_content	bool	Strip nav, footer, and boilerplate.
options.timeout	u32	Timeout in milliseconds.
options.wait_for	u32	Wait for page to render (milliseconds).
options.mobile	bool	Use a mobile viewport.
options.parsers	Vec<ParserConfig>	File parsers. ParserConfig::Simple("pdf") or ParserConfig::Pdf { parser_type, mode?, max_pages?, pages?, blocks?, page_markers? }.
options.actions	Vec<Action>	Pre-scrape browser actions: Wait, Click, Write, Press, Scroll, Screenshot, Scrape, ExecuteJavascript, Pdf.
options.location	LocationConfig	{ country, languages } for geo-aware scraping.
options.skip_tls_verification	bool	Skip TLS verification.
options.remove_base64_images	bool	Drop base64 images from markdown.
options.fast_mode	bool	Faster scrapes with reduced fidelity.
options.block_ads	bool	Block ads and cookie popups.
options.proxy	ProxyType	Basic, Stealth, Enhanced, Auto.
options.max_age	u32	Accept cached data up to this age (milliseconds).
options.min_age	u32	Accept cached data only if at least this old (milliseconds).
options.store_in_cache	bool	Cache the result.
options.lockdown	bool	Serve only previously cached results; never make outbound requests.
options.redact_pii	bool	Redact personally identifiable information.
options.audit_metadata	AuditMetadata	User attribution for SIEM logging. Has field username.
options.profile	ProfileConfig	Persistent browser profile: { name, save_changes? }.
options.json_options	JsonOptions	JSON extraction: { schema?, system_prompt?, prompt?, check_prompt_injection? }.
options.screenshot_options	ScreenshotOptions	Screenshot config: { full_page?, quality?, viewport? }.
options.change_tracking_options	ChangeTrackingOptions	Change tracking: { modes? (GitDiff, Json), schema?, prompt?, tag? }.
options.attribute_selectors	Vec<AttributeSelector>	Attribute extraction: { selector, attribute }.

Interact

Why use it

Control the browser session tied to a scrape job. Use for clicks, form fills, code execution, or natural-language browser instructions. Requires a scrape job ID from a prior scrape.

Preferred SDK method

client.interact(job_id, options) → Result<ScrapeExecuteResponse, FirecrawlError>

At least one of code or prompt must be provided, or the SDK returns FirecrawlError::Misuse.

Example

use firecrawl::{Client, ScrapeOptions, ScrapeExecuteOptions, ScrapeExecuteLanguage, Format};

let doc = client
    .scrape("https://example.com", ScrapeOptions {
        formats: Some(vec![Format::Markdown]),
        ..Default::default()
    })
    .await?;

let job_id = doc.metadata
    .as_ref()
    .and_then(|m| m.scrape_id.as_deref())
    .ok_or("Missing scrape_id")?;

// Natural-language interaction
let result = client
    .interact(job_id, ScrapeExecuteOptions {
        prompt: Some("Click the pricing tab and summarize the plans.".to_string()),
        ..Default::default()
    })
    .await?;

// Code-based interaction
let result = client
    .interact(job_id, ScrapeExecuteOptions {
        code: Some("console.log(await page.title());".to_string()),
        language: Some(ScrapeExecuteLanguage::Node),
        timeout: Some(60),
        ..Default::default()
    })
    .await?;

// Stop the session when done
client.stop_interaction(job_id).await?;

Parameters

Parameter	Type	Description
job_id	impl AsRef<str>	Scrape job ID from document.metadata.scrape_id.
options.code	Option<String>	Code to execute. At least one of code or prompt required.
options.prompt	Option<String>	Natural-language browser instruction. At least one of code or prompt required.
options.language	ScrapeExecuteLanguage	Runtime: Python, Node, Bash. Defaults to Node.
options.timeout	u32	Execution timeout in seconds.

client.stop_interaction(job_id) ends the browser session. Returns ScrapeBrowserDeleteResponse with success, optional session_duration_ms, credits_billed, error.

Notes

• Deprecated aliases: scrape_execute → interact; stop_interactive_browser and delete_scrape_browser → stop_interaction.
• ScrapeOptions uses dedicated sub-structs (json_options, screenshot_options, change_tracking_options) for advanced format configuration.
• search_and_scrape(query, limit) is a convenience helper returning Vec<Document> from web results.
• All types export at the crate root: use firecrawl::Client (not use firecrawl::v2::Client).
• Rust fields are snake_case but serialize to camelCase on the wire via serde.

Source Of Truth

• firecrawl/apps/rust-sdk/Cargo.toml
• firecrawl/apps/rust-sdk/src/client.rs
• firecrawl/apps/rust-sdk/src/scrape.rs
• firecrawl/apps/rust-sdk/src/search.rs
• firecrawl-docs/api-reference/v2-openapi.json