Rust - Firecrawl Docs

Instalación#

El SDK oficial de Rust está alojado en el monorepo de Firecrawl, en apps/rust-sdk.

Para instalar el SDK de Rust de Firecrawl, añade la dependencia desde crates.io:

[dependencies]firecrawl = "2"tokio = { version = "1", features = ["full"] }serde_json = "1"

O instálalo con Cargo:

cargo add firecrawlcargo add tokio --features fullcargo add serde_json

Note

Requiere Rust 1.70 o una versión posterior.

Uso#

Obtén una clave de API de firecrawl.dev
Configura la clave de API como una variable de entorno llamada FIRECRAWL_API_KEY o pásala directamente a Client::new(...)

Haz scraping de una página e imprime su contenido en markdown:

use firecrawl::{Client, ScrapeOptions, Format};#[tokio::main]async fn main() -> Result<(), Box<dyn std::error::Error>> {    let client = Client::new("fc-YOUR-API-KEY")?;    let doc = client.scrape(        "https://firecrawl.dev",        ScrapeOptions {            formats: Some(vec![Format::Markdown]),            ..Default::default()        },    ).await?;    println!("{}", doc.markdown.unwrap_or_default());    Ok(())}

Las secciones siguientes abarcan el rastreo, el mapeo, la búsqueda y los demás métodos del SDK.

Hacer scraping de una URL#

Para hacer scraping de una sola URL, usa el método scrape.

use firecrawl::{Client, ScrapeOptions, Format};let doc = client.scrape(    "https://firecrawl.dev",    ScrapeOptions {        formats: Some(vec![Format::Markdown, Format::Html]),        only_main_content: Some(true),        wait_for: Some(5000),        ..Default::default()    },).await?;println!("{}", doc.markdown.unwrap_or_default());if let Some(meta) = &doc.metadata {    println!("{:?}", meta.title);}

Extracción JSON#

Extrae JSON estructurado con scrape_with_schema:

use firecrawl::Client;use serde_json::json;let schema = json!({    "type": "object",    "properties": {        "name": { "type": "string" },        "price": { "type": "number" }    }});let data = client.scrape_with_schema(    "https://example.com/product",    schema,    Some("Extract the product name and price"),).await?;println!("{}", serde_json::to_string_pretty(&data)?);

O bien configura la extracción JSON directamente con ScrapeOptions:

use firecrawl::{Client, ScrapeOptions, Format, JsonOptions};use serde_json::json;let doc = client.scrape(    "https://example.com/product",    ScrapeOptions {        formats: Some(vec![Format::Json]),        json_options: Some(JsonOptions {            schema: Some(json!({                "type": "object",                "properties": {                    "name": { "type": "string" },                    "price": { "type": "number" }                }            })),            prompt: Some("Extract the product name and price".to_string()),            ..Default::default()        }),        ..Default::default()    },).await?;println!("{:?}", doc.json);

Procesamiento de archivos subidos#

Usa parse para subir un archivo local (.html, .htm, .pdf, .docx, .doc, .odt, .rtf, .xlsx, .xls) como datos de formulario multipart a /v2/parse. El endpoint devuelve un Document con los formatos solicitados.

ParseOptions omite intencionadamente los campos exclusivos de scrape que /v2/parse rechaza (como actions, waitFor, location, mobile, screenshot, branding y changeTracking).

Crea un ParseFile a partir de bytes en memoria o directamente desde una ruta:

use firecrawl::{Client, ParseFile, ParseFormat, ParseOptions};#[tokio::main]async fn main() -> Result<(), Box<dyn std::error::Error>> {    let client = Client::new("fc-YOUR-API-KEY")?;    let file = ParseFile::from_bytes(        "upload.html",        b"<!DOCTYPE html><html><body><h1>Rust Parse</h1></body></html>".to_vec(),    )    .with_content_type("text/html");    let options = ParseOptions {        formats: Some(vec![ParseFormat::Markdown, ParseFormat::Html]),        only_main_content: Some(true),        ..Default::default()    };    let doc = client.parse(file, Some(options)).await?;    println!("{}", doc.markdown.unwrap_or_default());    Ok(())}

O lee el archivo desde el disco y omite las opciones:

use firecrawl::{Client, ParseFile};let client = Client::new("fc-YOUR-API-KEY")?;let file = ParseFile::from_path("./report.pdf")?;let doc = client.parse(file, None).await?;println!("{}", doc.markdown.unwrap_or_default());

`ParseFile`#

Constructor	Descripción
`ParseFile::from_bytes(filename, bytes)`	Crea una instancia a partir de un nombre de archivo y bytes en memoria
`ParseFile::from_path(path)`	Lee los bytes desde el disco y obtiene el nombre del archivo
`.with_content_type(content_type)`	Añade una sugerencia de tipo MIME (p. ej., `text/html`, `application/pdf`)

`ParseOptions`#

Campos admitidos (todos opcionales, en camelCase en la solicitud):

formats: Vec<ParseFormat> — cualquiera de Markdown, Html, RawHtml, Links, Images, Summary, Json, Attributes
only_main_content: bool
include_tags: Vec<String> / exclude_tags: Vec<String>
headers: HashMap<String, String>
timeout: u32 (ms)
parsers: Vec<ParserConfig> (p. ej., configuración del analizador de PDF)
skip_tls_verification: bool
remove_base64_images: bool
fast_mode: bool
block_ads: bool
proxy: ParseProxyType (Basic o Auto)
json_options: JsonOptions
attribute_selectors: Vec<AttributeSelector>
zero_data_retention: bool
integration: String, origin: String, use_mock: String

Rastreo de un sitio web#

Para rastrear un sitio web y esperar a que finalice, usa crawl.

use firecrawl::{Client, CrawlOptions, ScrapeOptions, Format};let job = client.crawl(    "https://firecrawl.dev",    CrawlOptions {        limit: Some(50),        max_discovery_depth: Some(3),        scrape_options: Some(ScrapeOptions {            formats: Some(vec![Format::Markdown]),            ..Default::default()        }),        ..Default::default()    },).await?;println!("Status: {:?}", job.status);println!("Progress: {}/{}", job.completed, job.total);for page in &job.data {    if let Some(meta) = &page.metadata {        println!("{:?}", meta.source_url);    }}

Iniciar un rastreo#

Inicia un trabajo sin esperar utilizando start_crawl.

use firecrawl::{Client, CrawlOptions};let start = client.start_crawl(    "https://firecrawl.dev",    CrawlOptions {        limit: Some(100),        ..Default::default()    },).await?;println!("Job ID: {}", start.id);

Consultar el estado del rastreo#

Consulta el progreso del rastreo con get_crawl_status.

let status = client.get_crawl_status(&start.id).await?;println!("Status: {:?}", status.status);println!("Progress: {}/{}", status.completed, status.total);

Cancelar un rastreo#

Cancela un rastreo en curso con cancel_crawl.

let result = client.cancel_crawl(&start.id).await?;println!("{:?}", result);

Comprobar errores de rastreo#

Recupera los errores de un trabajo de rastreo con get_crawl_errors.

let errors = client.get_crawl_errors(&start.id).await?;println!("{:?}", errors);

Mapeo de un sitio web#

Descubre enlaces de un sitio con map.

use firecrawl::{Client, MapOptions};let response = client.map(    "https://firecrawl.dev",    MapOptions {        limit: Some(100),        search: Some("blog".to_string()),        ..Default::default()    },).await?;for link in &response.links {    println!("{} - {}", link.url, link.title.as_deref().unwrap_or(""));}

Para obtener un resultado más simple, solo con URL, usa map_urls:

let urls = client.map_urls("https://firecrawl.dev", None).await?;for url in &urls {    println!("{}", url);}

Búsqueda en la web#

Busca con opciones de configuración al utilizar search.

use firecrawl::{Client, SearchOptions};let results = client.search(    "firecrawl web scraping",    SearchOptions {        limit: Some(10),        ..Default::default()    },).await?;if let Some(web) = results.data.web {    for item in web {        match item {            firecrawl::SearchResultOrDocument::WebResult(r) => {                println!("{} - {}", r.url, r.title.unwrap_or_default());            }            firecrawl::SearchResultOrDocument::Document(d) => {                println!("{}", d.markdown.unwrap_or_default());            }        }    }}

Para un método de conveniencia que devuelve directamente los documentos extraídos:

let docs = client.search_and_scrape("firecrawl web scraping", 5).await?;for doc in &docs {    println!("{}", doc.markdown.as_deref().unwrap_or(""));}

Scraping por lotes#

Realiza scraping de varias URL en paralelo con batch_scrape.

use firecrawl::{Client, BatchScrapeOptions, ScrapeOptions, Format};let urls = vec![    "https://firecrawl.dev".to_string(),    "https://firecrawl.dev/blog".to_string(),];let job = client.batch_scrape(    urls,    BatchScrapeOptions {        options: Some(ScrapeOptions {            formats: Some(vec![Format::Markdown]),            ..Default::default()        }),        ..Default::default()    },).await?;for doc in &job.data {    println!("{}", doc.markdown.as_deref().unwrap_or(""));}

Agente#

Ejecuta un agente basado en IA con agent.

use firecrawl::{Client, AgentOptions};let result = client.agent(    AgentOptions {        prompt: "Find the pricing plans for Firecrawl and compare them".to_string(),        ..Default::default()    },).await?;println!("{:?}", result.data);

Con un esquema JSON para una salida estructurada:

use firecrawl::{Client, AgentOptions, AgentModel};use serde::Deserialize;use serde_json::json;#[derive(Debug, Deserialize)]struct PricingPlan {    name: String,    price: String,}#[derive(Debug, Deserialize)]struct PricingData {    plans: Vec<PricingPlan>,}let schema = json!({    "type": "object",    "properties": {        "plans": {            "type": "array",            "items": {                "type": "object",                "properties": {                    "name": { "type": "string" },                    "price": { "type": "string" }                }            }        }    }});let result: Option<PricingData> = client.agent_with_schema(    vec!["https://firecrawl.dev".to_string()],    "Extract pricing plan details",    schema,).await?;if let Some(data) = result {    for plan in &data.plans {        println!("{}: {}", plan.name, plan.price);    }}

Sesión interactiva vinculada al scraping#

Usa un ID de trabajo de scraping para ejecutar código adicional del navegador en el mismo contexto:

interact(...) ejecuta código o prompts en la sesión del navegador vinculada al scraping.
stop_interaction(...) detiene la sesión interactiva cuando hayas terminado.

use firecrawl::{Client, ScrapeExecuteOptions, ScrapeExecuteLanguage};let scrape_job_id = "550e8400-e29b-41d4-a716-446655440000";// Ejecutar código en la sesión del browserlet run = client.interact(    scrape_job_id,    ScrapeExecuteOptions {        code: Some("console.log(await page.title())".to_string()),        language: Some(ScrapeExecuteLanguage::Node),        timeout: Some(60),        ..Default::default()    },).await?;println!("{:?}", run.stdout);// O usar un prompt en lenguaje naturallet run = client.interact(    scrape_job_id,    ScrapeExecuteOptions {        prompt: Some("Click the pricing tab and summarize the plans".to_string()),        ..Default::default()    },).await?;// Detener la sesión cuando se termineclient.stop_interaction(scrape_job_id).await?;

Configuración#

Client::new(...) y Client::new_selfhosted(...) crean el cliente.

Opción	Descripción
`Client::new(api_key)`	Crea un cliente para el servicio en la nube de Firecrawl (`https://api.firecrawl.dev`)
`Client::new_selfhosted(api_url, api_key)`	Crea un cliente para una instancia autogestionada de Firecrawl

use firecrawl::Client;// Servicio en la nubelet client = Client::new("fc-your-api-key")?;// Autogestionadolet client = Client::new_selfhosted(    "http://localhost:3002",    Some("fc-your-api-key"),)?;// Autogestionado sin autenticaciónlet client = Client::new_selfhosted(    "http://localhost:3002",    None::<&str>,)?;

Variable de entorno#

Define la variable de entorno FIRECRAWL_API_KEY en lugar de pasar la clave directamente:

export FIRECRAWL_API_KEY=fc-YOUR-API-KEY

let api_key = std::env::var("FIRECRAWL_API_KEY")    .expect("FIRECRAWL_API_KEY must be set");let client = Client::new(api_key)?;

Intervalos de sondeo#

Los métodos síncronos (crawl, batch_scrape, agent) siguen consultando el estado hasta completarse. Puedes personalizar el intervalo de sondeo mediante la estructura options:

use firecrawl::CrawlOptions;let options = CrawlOptions {    limit: Some(50),    poll_interval: Some(3000), // Consultar cada 3 segundos (predeterminado: 2000ms)    ..Default::default()};

Manejo de errores#

El SDK usa el enum FirecrawlError, que implementa Error, Debug y Display. Todos los métodos devuelven Result<T, FirecrawlError>.

use firecrawl::{Client, FirecrawlError};match client.scrape("https://example.com", None).await {    Ok(doc) => println!("{}", doc.markdown.unwrap_or_default()),    Err(FirecrawlError::HttpRequestFailed(action, status, msg)) => {        eprintln!("HTTP {}: {} ({})", status, msg, action);    }    Err(FirecrawlError::APIError(action, api_err)) => {        eprintln!("API error ({}): {}", action, api_err.error);    }    Err(FirecrawlError::JobFailed(msg)) => {        eprintln!("Job failed: {}", msg);    }    Err(FirecrawlError::Misuse(msg)) => {        eprintln!("SDK misuse: {}", msg);    }    Err(e) => eprintln!("Error: {}", e),}

¿Eres un agente de IA que necesita una clave de API de Firecrawl? Consulta firecrawl.dev/agent-onboarding/SKILL.md para obtener instrucciones de incorporación automatizadas.

Instalación#

Uso#

Hacer scraping de una URL#

Extracción JSON#

Procesamiento de archivos subidos#

ParseFile#

ParseOptions#

Rastreo de un sitio web#

Iniciar un rastreo#

Consultar el estado del rastreo#

Cancelar un rastreo#

Comprobar errores de rastreo#

Mapeo de un sitio web#

Búsqueda en la web#

Scraping por lotes#

Agente#

Sesión interactiva vinculada al scraping#

Configuración#

Variable de entorno#

Intervalos de sondeo#

Manejo de errores#

`ParseFile`#

`ParseOptions`#