Rust Agent Quickstart

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

Firecrawl Rust Agent Quickstart

Canonical quickstart for external agents. Generated from SDK source (firecrawl crate v2.18.0) and the v2 OpenAPI spec. Method names, parameters, and types match the SDK public API.

Install

cargo add firecrawl

Requires an async runtime (Tokio).

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:, for example site:docs.firecrawl.dev crawl webhooks.

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]),
    limit: Some(5),
    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?;

if let Some(web) = results.data.web {
    for item in web {
        // item is SearchResultOrDocument::WebResult(...) or ::Document(...)
    }
}

Parameters

Parameter	Type	Description
query	impl AsRef<str>	Search query. Use site:example.com to limit to a domain.
options.sources	Vec<SearchSource>	Which sources: Web, News, Images.
options.categories	Vec<SearchCategory>	Filter by category: Github, Research, Pdf.
options.include_domains	Vec<String>	Only include these domains.
options.exclude_domains	Vec<String>	Exclude these domains.
options.limit	u32	Max results. Doc comment says default 5, max 20.
options.tbs	String	Time-based filter (e.g. qdr:d, qdr:w).
options.location	String	Location for localized results.
options.ignore_invalid_urls	bool	Drop unscrappable URLs.
options.highlights	bool	Return query-relevant highlights. Defaults to true.
options.timeout	u32	Request timeout in milliseconds.
options.scrape_options	ScrapeOptions	Scrape each result (see Scrape parameters).

Scrape

Why use it

Fetch structured content from a URL in one or more formats. Use when you already have the URL.

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::Json]),
        json_options: Some(JsonOptions {
            prompt: Some("Extract plan names and prices.".to_string()),
            ..Default::default()
        }),
        only_main_content: Some(true),
        ..Default::default()
    })
    .await?;

Parameters

Parameter	Type	Description
url	impl AsRef<str>	URL to scrape.
options.formats	Vec<Format>	Output formats (see below).
options.headers	HashMap<String, String>	Custom request headers.
options.include_tags	Vec<String>	Include only these HTML tags.
options.exclude_tags	Vec<String>	Exclude these HTML tags.
options.only_main_content	bool	Strip nav, footer, 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 parsing controls (e.g. ParserConfig::Pdf { ... }).
options.actions	Vec<Action>	Pre-scrape browser actions (Click, Wait, Write, Press, Scroll, Scrape, ExecuteJavascript, Screenshot, Pdf).
options.location	LocationConfig	Geo/language-aware scraping: country, languages.
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	Proxy mode: Basic, Stealth, Enhanced, Auto.
options.max_age	u32	Use cached data up to this age (milliseconds).
options.store_in_cache	bool	Cache the result.
options.lockdown	bool	Serve only cached results.
options.profile	ProfileConfig	Persistent browser profile: name, save_changes.
options.json_options	JsonOptions	JSON extraction config: schema, prompt, system_prompt.
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.

Format enum values:

Simple: Markdown, Html, RawHtml, Links, Images, Screenshot, Summary, ChangeTracking, Json, Attributes, Branding, Product, Menu, Audio, Video.

Object variants: Question(QuestionFormat { question }), Highlights(HighlightsFormat { query }).

Interact

Why use it

Control the browser session tied to a scrape job. Use for code execution or natural-language instructions after a scrape creates a session.

Preferred SDK method

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

Example

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

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.get("scrapeId"))
    .and_then(|v| v.as_str())
    .expect("Missing scrapeId");

// 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?;

// Or code-based interaction
let code_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?;

// Clean up
client.stop_interaction(job_id).await?;

Parameters

Parameter	Type	Description
job_id	impl AsRef<str>	Scrape job ID from document metadata.
options.code	Option<String>	Code to run in the browser session.
options.prompt	Option<String>	Natural-language instruction for the browser agent.
options.language	ScrapeExecuteLanguage	Runtime: Python, Node, Bash. Default: Node.
options.timeout	u32	Execution timeout in seconds.

At least one of code or prompt must be non-empty (SDK returns FirecrawlError::Misuse otherwise).

Stop session: client.stop_interaction(job_id) ends the browser session.

Notes

• Deprecated aliases: scrape_execute → interact; stop_interactive_browser / delete_scrape_browser → stop_interaction.
• All option structs derive Default; use struct-update syntax: ScrapeOptions { formats: Some(vec![...]), ..Default::default() }.
• The options parameter on scrape and search accepts impl Into<Option<T>>, so you can pass None or a bare struct.
• All methods are async and require a Tokio runtime.
• search_and_scrape(query, limit) is a convenience helper that returns Vec<Document>.
• All serialization uses camelCase for the API wire format.

Source Of Truth

• firecrawl/apps/rust-sdk/Cargo.toml
• firecrawl/apps/rust-sdk/src/lib.rs
• 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