Rust Agent Quickstart

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

Firecrawl Rust Agent Quickstart

This file is the canonical quickstart for external agents integrating with Firecrawl using the Rust SDK. It is generated from SDK source and OpenAPI spec.

Install

cargo add firecrawl

Authenticate

use firecrawl::Client;

let app = Client::new("fc-YOUR_API_KEY")?;

For self-hosted instances:

let app = Client::new_selfhosted("https://your-instance.com", Some("fc-YOUR_API_KEY"))?;

Passing None for the API key uses the keyless free tier (rate-limited per IP).

When To Use What

• search: Use when you start with a query and need to discover relevant pages. Returns ranked results with optional scraping of each result.
• scrape: Use when you already have a URL and want its content in markdown, HTML, JSON, or other formats.
• interact: Use when a page needs post-scrape browser actions — clicking, filling forms, running code, or prompting an AI agent in the browser.

Search

Why use it

Search the web for a query and get back ranked results. Optionally scrape each result page inline by setting scrape_options.

Preferred SDK method

app.search(query, options).await

Example

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

let app = Client::new("fc-YOUR_API_KEY")?;

let response = app.search("firecrawl web scraping API", SearchOptions {
    limit: Some(5),
    scrape_options: Some(ScrapeOptions::default()),
    ..Default::default()
}).await?;

if let Some(web) = response.data.web {
    for item in web {
        println!("{:?}", item);
    }
}

Parameters

All fields on SearchOptions are Option and default to None.

Parameter	Type	Description
query	impl AsRef<str>	Required. The search query (first positional argument).
limit	Option<u32>	Max results. Default: 5, max: 20.
sources	Option<Vec<SearchSource>>	Sources: SearchSource::Web, News, Images.
categories	Option<Vec<SearchCategory>>	Filter: SearchCategory::Github, Research, Pdf.
include_domains	Option<Vec<String>>	Restrict results to these domains.
exclude_domains	Option<Vec<String>>	Exclude results from these domains.
tbs	Option<String>	Time-based search filter (e.g. "qdr:d" for past day).
location	Option<String>	Location string for geo-targeted results.
ignore_invalid_urls	Option<bool>	Ignore invalid URLs in results.
timeout	Option<u32>	Timeout in milliseconds.
highlights	Option<bool>	Generate query-relevant highlights. Default: true.
scrape_options	Option<ScrapeOptions>	Scrape options applied to each result page.
integration	Option<String>	Integration identifier for tracking.

Returns: SearchResponse containing SearchData with optional .web, .news, and .images vectors.

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

Scrape

Why use it

Scrape a single URL and get its content as markdown, HTML, structured JSON, screenshots, or other formats.

Preferred SDK method

app.scrape(url, options).await

Example

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

let app = Client::new("fc-YOUR_API_KEY")?;

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

println!("{}", doc.markdown.unwrap_or_default());

Parameters

All fields on ScrapeOptions are Option and default to None.

Parameter	Type	Description
url	impl AsRef<str>	Required. The URL to scrape (first positional argument).
formats	Option<Vec<Format>>	Output formats: Markdown, Html, RawHtml, Links, Images, Screenshot, Summary, Json, ChangeTracking, Branding, Product, Menu, Audio, Video, Question(QuestionFormat), Highlights(HighlightsFormat).
only_main_content	Option<bool>	Extract only the main content, excluding headers/navs/footers.
include_tags	Option<Vec<String>>	HTML tags to include in output.
exclude_tags	Option<Vec<String>>	HTML tags to exclude from output.
timeout	Option<u32>	Timeout in milliseconds.
wait_for	Option<u32>	Delay in ms before fetching content.
mobile	Option<bool>	Emulate a mobile device.
headers	Option<HashMap<String, String>>	Custom HTTP headers.
actions	Option<Vec<Action>>	Browser actions before scraping.
parsers	Option<Vec<ParserConfig>>	Parser configs for file processing (e.g. PDF).
location	Option<LocationConfig>	Geo-location with country and languages fields.
skip_tls_verification	Option<bool>	Skip TLS certificate verification.
remove_base64_images	Option<bool>	Remove base64 images from output.
fast_mode	Option<bool>	Enable fast mode (less accuracy).
block_ads	Option<bool>	Block ads and cookie popups.
proxy	Option<ProxyType>	Proxy tier: Basic, Stealth, Enhanced, Auto.
max_age	Option<u32>	Use cached result if younger than this (seconds).
min_age	Option<u32>	Min age for cache-only check (seconds).
store_in_cache	Option<bool>	Store result in Firecrawl cache.
lockdown	Option<bool>	Serve from cache only.
redact_pii	Option<bool>	Redact PII from returned content.
audit_metadata	Option<AuditMetadata>	User attribution for SIEM logging.
profile	Option<ProfileConfig>	Persistent browser profile (name, save_changes).
integration	Option<String>	Integration identifier.
json_options	Option<JsonOptions>	JSON extraction options (schema, prompt, system_prompt, check_prompt_injection).
screenshot_options	Option<ScreenshotOptions>	Screenshot options (full_page, quality, viewport).
change_tracking_options	Option<ChangeTrackingOptions>	Change tracking options (modes, schema, prompt, tag).
attribute_selectors	Option<Vec<AttributeSelector>>	Attribute extraction selectors.

Returns: Document with optional fields like markdown, html, raw_html, links, images, screenshot, metadata, etc.

A convenience method scrape_with_schema(url, schema, prompt) extracts structured JSON using a JSON Schema.

Interact

Why use it

Execute code or send a natural-language prompt in the browser session of a previous scrape job. Use this for clicking buttons, filling forms, navigating multi-step flows, or running arbitrary JavaScript/Python/Bash in the browser sandbox.

Preferred SDK method

app.interact(job_id, options).await

Example

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

let app = Client::new("fc-YOUR_API_KEY")?;

let doc = app.scrape("https://example.com", ScrapeOptions::default()).await?;
let job_id = doc.metadata.as_ref()
    .and_then(|m| m.additional.get("jobId"))
    .and_then(|v| v.as_str())
    .unwrap();

let result = app.interact(job_id, ScrapeExecuteOptions {
    code: Some("document.querySelector('button.load-more').click();".into()),
    language: None, // defaults to Node
    timeout: Some(30),
    ..Default::default()
}).await?;

println!("{:?}", result.stdout);

Parameters

Parameter	Type	Description
job_id	impl AsRef<str>	Required. The scrape job ID.
code	Option<String>	Code to execute. One of code or prompt is required.
prompt	Option<String>	Natural-language instruction for the AI browser agent. One of code or prompt is required.
language	Option<ScrapeExecuteLanguage>	Execution language: Python, Node, Bash. Default: Node.
timeout	Option<u32>	Execution timeout in seconds (1–300).

Returns: ScrapeExecuteResponse with success, stdout, stderr, result, exit_code, killed, error, and optional live_view_url / interactive_live_view_url.

Stop the session:

app.stop_interaction(job_id).await?;

Notes

• Struct fields use snake_case (e.g. only_main_content, skip_tls_verification). They serialize to camelCase JSON automatically.
• All option structs derive Default, so use ..Default::default() to fill unset fields.
• Methods accept impl Into<Option<ScrapeOptions>> and impl Into<Option<SearchOptions>>, so you can pass None, a bare struct, or Some(struct).
• The interact method requires ScrapeExecuteOptions directly (not wrapped in Option) since at least code or prompt must be set.
• Deprecated aliases (use the preferred names instead):
  • scrape_execute() → interact()
  • stop_interactive_browser() / delete_scrape_browser() → stop_interaction()

Source Of Truth

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