.NET - Firecrawl Docs

Instalación#

El SDK oficial de Firecrawl para .NET se mantiene en el monorepo de Firecrawl, en apps/dot-net-sdk.

Para instalar el SDK de Firecrawl para .NET, agrega el paquete NuGet:

dotnet add package firecrawl-sdk

Install-Package firecrawl-sdk

<PackageReference Include="firecrawl-sdk" Version="1.0.0" />

Note

Requiere .NET 8.0 o 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 al constructor de FirecrawlClient

Aquí tienes un ejemplo rápido con la API actual del SDK:

using Firecrawl;using Firecrawl.Models;var client = new FirecrawlClient("fc-your-api-key");// Hacer scraping de una sola páginavar doc = await client.ScrapeAsync("https://firecrawl.dev",    new ScrapeOptions { Formats = new List<object> { "markdown" } });// Rastrear un sitio webvar job = await client.CrawlAsync("https://firecrawl.dev",    new CrawlOptions { Limit = 5 });Console.WriteLine(doc.Markdown);Console.WriteLine($"Crawled pages: {job.Data?.Count ?? 0}");

Hacer scraping de una URL#

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

using Firecrawl.Models;var doc = await client.ScrapeAsync("https://firecrawl.dev",    new ScrapeOptions    {        Formats = new List<object> { "markdown", "html" },        OnlyMainContent = true,        WaitFor = 5000    });Console.WriteLine(doc.Markdown);Console.WriteLine(doc.Metadata?["title"]);

Extracción JSON#

Extrae JSON estructurado con JsonFormat a través del endpoint de scraping:

using Firecrawl.Models;var jsonFmt = new JsonFormat{    Prompt = "Extract the product name and price",    Schema = new Dictionary<string, object>    {        ["type"] = "object",        ["properties"] = new Dictionary<string, object>        {            ["name"] = new Dictionary<string, object> { ["type"] = "string" },            ["price"] = new Dictionary<string, object> { ["type"] = "number" }        }    }};var doc = await client.ScrapeAsync("https://example.com/product",    new ScrapeOptions    {        Formats = new List<object> { jsonFmt }    });Console.WriteLine(doc.Json);

Rastreo de un sitio web#

Para rastrear un sitio web y esperar a que finalice, usa CrawlAsync. Este método gestiona el sondeo y la paginación automáticamente.

using Firecrawl.Models;var job = await client.CrawlAsync("https://firecrawl.dev",    new CrawlOptions    {        Limit = 50,        MaxDiscoveryDepth = 3,        ScrapeOptions = new ScrapeOptions        {            Formats = new List<object> { "markdown" }        }    });Console.WriteLine($"Status: {job.Status}");Console.WriteLine($"Progress: {job.Completed}/{job.Total}");if (job.Data != null){    foreach (var page in job.Data)    {        Console.WriteLine(page.Metadata?["sourceURL"]);    }}

Iniciar un rastreo#

Inicia un trabajo sin esperar con StartCrawlAsync.

using Firecrawl.Models;var start = await client.StartCrawlAsync("https://firecrawl.dev",    new CrawlOptions { Limit = 100 });Console.WriteLine($"Job ID: {start.Id}");

Consultar el estado del rastreo#

Consulta el progreso del rastreo con GetCrawlStatusAsync.

var status = await client.GetCrawlStatusAsync(start.Id!);Console.WriteLine($"Status: {status.Status}");Console.WriteLine($"Progress: {status.Completed}/{status.Total}");

Cancelar un rastreo#

Cancela un rastreo en curso con CancelCrawlAsync.

var result = await client.CancelCrawlAsync(start.Id!);Console.WriteLine(result);

Mapeo de un sitio web#

Descubre enlaces en un sitio con MapAsync.

using Firecrawl.Models;var data = await client.MapAsync("https://firecrawl.dev",    new MapOptions    {        Limit = 100,        Search = "blog"    });if (data.Links != null){    foreach (var link in data.Links)    {        Console.WriteLine(link);    }}

Búsqueda en la Web#

Realiza búsquedas con opciones de búsqueda opcionales utilizando SearchAsync.

using Firecrawl.Models;var results = await client.SearchAsync("firecrawl web scraping",    new SearchOptions    {        Limit = 10,        Location = "US"    });if (results.Web != null){    foreach (var hit in results.Web)    {        Console.WriteLine($"{hit.Title} - {hit.Url}");    }}

Scraping por lotes#

Realiza scraping de varias URL en paralelo con BatchScrapeAsync. Este método se encarga del sondeo y la paginación automáticamente.

using Firecrawl.Models;var urls = new List<string>{    "https://firecrawl.dev",    "https://firecrawl.dev/blog"};var job = await client.BatchScrapeAsync(urls,    new BatchScrapeOptions    {        Options = new ScrapeOptions        {            Formats = new List<object> { "markdown" }        }    });if (job.Data != null){    foreach (var doc in job.Data)    {        Console.WriteLine(doc.Markdown);    }}

Extracción por lotes con clave de idempotencia#

Para evitar que se procesen solicitudes duplicadas, pasa una IdempotencyKey:

var job = await client.BatchScrapeAsync(urls,    new BatchScrapeOptions    {        IdempotencyKey = "my-unique-key",        Options = new ScrapeOptions        {            Formats = new List<object> { "markdown" }        }    });

Uso y métricas#

Consulta la concurrencia y los créditos restantes:

using Firecrawl.Models;var concurrency = await client.GetConcurrencyAsync();Console.WriteLine($"Concurrency: {concurrency.Current}/{concurrency.MaxConcurrency}");var credits = await client.GetCreditUsageAsync();Console.WriteLine($"Remaining credits: {credits.RemainingCredits}");

Compatibilidad con async#

Todos los métodos del SDK de Firecrawl para .NET son async de forma predeterminada y devuelven Task<T>. Admiten CancellationToken para una cancelación cooperativa.

using Firecrawl.Models;using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));var doc = await client.ScrapeAsync("https://example.com",    new ScrapeOptions    {        Formats = new List<object> { "markdown" }    },    cancellationToken: cts.Token);Console.WriteLine(doc.Markdown);

Configuración#

El constructor de FirecrawlClient admite las siguientes opciones:

Opción	Tipo	Predeterminado	Descripción
`apiKey`	`string?`	Variable de entorno `FIRECRAWL_API_KEY`	Tu clave de la API de Firecrawl
`apiUrl`	`string?`	`https://api.firecrawl.dev` (o `FIRECRAWL_API_URL`)	URL base de la API
`timeout`	`TimeSpan?`	5 minutos	Tiempo de espera de la solicitud HTTP
`maxRetries`	`int`	`3`	Reintentos automáticos ante fallos transitorios
`backoffFactor`	`double`	`0.5`	Factor de retroceso exponencial en segundos
`httpClient`	`HttpClient?`	Se crea a partir de `timeout`	Instancia de HttpClient preconfigurada

using Firecrawl;var client = new FirecrawlClient(    apiKey: "fc-your-api-key",    apiUrl: "https://api.firecrawl.dev",    timeout: TimeSpan.FromMinutes(5),    maxRetries: 3,    backoffFactor: 0.5);

Cliente HTTP personalizado#

Puedes pasar un HttpClient preconfigurado para controlar el pool de conexiones, los proxies, los manejadores de mensajes y cualquier otra funcionalidad de HttpClient. Cuando se proporciona, la configuración de timeout se ignora y prevalece la propia configuración del cliente.

using Firecrawl;var handler = new HttpClientHandler{    Proxy = new WebProxy("http://proxy.example.com:8080"),    UseProxy = true};var httpClient = new HttpClient(handler){    Timeout = TimeSpan.FromSeconds(60)};var client = new FirecrawlClient(    apiKey: "fc-your-api-key",    httpClient: httpClient);

Configuración de variables de entorno#

El SDK obtiene la configuración a partir de variables de entorno cuando se omiten los parámetros del constructor:

// Usa las variables de entorno FIRECRAWL_API_KEY y FIRECRAWL_API_URLvar client = new FirecrawlClient();

Manejo de errores#

El SDK lanza excepciones específicas bajo Firecrawl.Exceptions.

using Firecrawl.Exceptions;using Firecrawl.Models;try{    var doc = await client.ScrapeAsync("https://example.com");}catch (AuthenticationException ex){    Console.Error.WriteLine($"Auth failed: {ex.Message}");}catch (RateLimitException ex){    Console.Error.WriteLine($"Rate limited: {ex.Message}");}catch (JobTimeoutException ex){    Console.Error.WriteLine($"Job {ex.JobId} timed out after {ex.TimeoutSeconds}s");}catch (FirecrawlException ex){    Console.Error.WriteLine($"Error {ex.StatusCode}: {ex.Message}");}

La jerarquía de excepciones:

Exception	HTTP Code	When
`AuthenticationException`	401	Clave de API no válida o ausente
`RateLimitException`	429	Demasiadas solicitudes
`JobTimeoutException`	—	El trabajo asíncrono (crawl/extracción por lotes) no se completó a tiempo
`FirecrawlException`	varía	Excepción base para todos los demás errores de la API

Los fallos transitorios (408, 409, 502 y otros errores 5xx) se reintentan automáticamente con backoff exponencial antes de que se lance una excepción.

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