> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Scrape, crawl, and search the web with Firecrawl in Guild agents

> Connect Guild agents to Firecrawl with an API key to scrape pages into markdown or JSON, crawl and map sites, search the web, and extract structured data.

Integrations · Firecrawl

Guild agents use Firecrawl to turn web pages into clean markdown or structured JSON: scrape one page, crawl or map a whole site, search the web and scrape the results, or extract fields with a schema. Guild stores your Firecrawl API key and injects it server-side, so agent code never sees it.

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Firecrawl.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Firecrawl to your first agent.

## What the Firecrawl integration exposes

The integration is `guildai~firecrawl`, and it calls Firecrawl's v2 API at `https://api.firecrawl.dev/v2`. Tools cover single and batch scrapes, crawls and their status, site maps, search with scraping, schema-based extraction, Firecrawl's research agent, browser sessions, and credit and token usage.

Crawls, batch scrapes, extractions, and agent runs are asynchronous. The start tool returns a job ID, and the agent polls the matching status tool, such as `firecrawl_get_crawl_status`, until the job finishes.

## How it works

**1. Create a Firecrawl API key**

Open [API keys](https://www.firecrawl.dev/app/api-keys) in Firecrawl and create a key. It starts with `fc-`.

**2. Connect the key in Guild**

Go to **Access & setup > Credentials**, click **Connect**, select **firecrawl**, and paste the key into **API Key**.

**3. Import the tools you need**

Import `FirecrawlTools` from `@guildai-services/guildai~firecrawl` and use `pick()` to give the agent only the tools its job needs.

## Why Firecrawl access needs governing

Every Firecrawl call spends credits, and a crawl can spend many. Guild keeps the key server-side and checks every request against your [credential policies](https://docs.guild.ai/platform/credential-policies.md), so you can let one agent scrape single pages while denying crawls and agent runs. Give each team its own [credential](https://docs.guild.ai/platform/credentials.md) to keep spend attributable.

## Authentication

* **Type:** API key
* **Header:** Guild sends the key as `Authorization: Bearer <key>`

See [Credentials](https://docs.guild.ai/platform/credentials.md) for workspace, member, and agent-scoped credentials.

## Usage

```typescript theme={null}
import { FirecrawlTools } from "@guildai-services/guildai~firecrawl"
import { llmAgent, pick } from "@guildai/agents-sdk"

export default llmAgent({
  systemPrompt: "You read competitor pricing pages and summarize changes.",
  tools: {
    ...pick(FirecrawlTools, [
      "firecrawl_scrape_and_extract_from_url",
      "firecrawl_map_urls",
      "firecrawl_search_and_scrape",
    ]),
  },
})
```

Tools are named with the `firecrawl_` prefix.

## Tools

Tools in the latest published version of `guildai~firecrawl`:

> [accordion] All 32 tools
>
> | Tool | What it does |
> | - | - |
> | `firecrawl_cancel_agent` | Cancel agent. |
> | `firecrawl_cancel_batch_scrape` | Cancel batch scrape. |
> | `firecrawl_cancel_crawl` | Cancel crawl. |
> | `firecrawl_crawl_params_preview` | Crawl params preview. |
> | `firecrawl_crawl_urls` | Crawl urls. |
> | `firecrawl_create_browser_session` | Create browser session. |
> | `firecrawl_delete_browser_session` | Delete browser session. |
> | `firecrawl_execute_browser_code` | Execute browser code. |
> | `firecrawl_extract_data` | Extract data. |
> | `firecrawl_get_active_crawls` | Get active crawls. |
> | `firecrawl_get_activity` | Lists your team's recent API activity from the last 24 hours. |
> | `firecrawl_get_agent_status` | Get agent status. |
> | `firecrawl_get_batch_scrape_errors` | Get batch scrape errors. |
> | `firecrawl_get_batch_scrape_status` | Get batch scrape status. |
> | `firecrawl_get_crawl_errors` | Get crawl errors. |
> | `firecrawl_get_crawl_status` | Get crawl status. |
> | `firecrawl_get_credit_usage` | Get credit usage. |
> | `firecrawl_get_extract_status` | Get extract status. |
> | `firecrawl_get_historical_credit_usage` | Get historical credit usage. |
> | `firecrawl_get_historical_token_usage` | Get historical token usage. |
> | `firecrawl_get_queue_status` | Get queue status. |
> | `firecrawl_get_token_usage` | Get token usage. |
> | `firecrawl_interact_with_scrape_browser_session` | Interact with scrape browser session. |
> | `firecrawl_list_browser_sessions` | List browser sessions. |
> | `firecrawl_map_urls` | Map urls. |
> | `firecrawl_scrape_and_extract_from_url` | Scrape and extract from url. |
> | `firecrawl_scrape_and_extract_from_urls` | Scrape and extract from urls. |
> | `firecrawl_search_and_scrape` | Search and scrape. |
> | `firecrawl_start_agent` | Start agent. |
> | `firecrawl_stop_interactive_scrape_browser_session` | Stop interactive scrape browser session. |
> | `firecrawl_support_ask` | Support ask. |
> | `firecrawl_support_docs_search` | Support docs search. |

## Frequently asked questions

> [accordion] Can a finished Firecrawl crawl trigger a Guild agent?
>
> Not directly. The integration lists `crawl` and `batch_scrape` events, but Firecrawl sends its webhooks in its own format, signed with an `X-Firecrawl-Signature` header. Guild accepts webhooks for this integration only in [its own format](https://docs.guild.ai/services/create-an-integration.md#webhook-format), so Firecrawl's deliveries are rejected. Have the agent poll the job's status tool instead.

> [accordion] How do I keep an agent from running up Firecrawl credits?
>
> Deny the expensive operations, such as `firecrawl_crawl_urls` and `firecrawl_start_agent`, in a credential policy, and give the agent `firecrawl_get_credit_usage` so it can check its balance. See [Credential policies](https://docs.guild.ai/platform/credential-policies.md).

> [accordion] Does this integration use Firecrawl's v1 API?
>
> No. It calls the v2 API. Firecrawl's v1 endpoints and the Firecrawl MCP server aren't part of this integration.

## Related

**Also runs on Guild:** [Browserbase](https://docs.guild.ai/integrations/browserbase.md) · [Pinecone](https://docs.guild.ai/integrations/pinecone.md)

**Read:** Docs: [Credential policies](https://docs.guild.ai/platform/credential-policies.md) · [Credentials](https://docs.guild.ai/platform/credentials.md) · [Tools in agents](https://docs.guild.ai/sdk/tools.md)