Firecrawl

43 toolsAPI key

firecrawl_example.py

import os

from charter.packs import firecrawl

firecrawl.configure(api_key=os.environ["FIRECRAWL_API_KEY"])

page = await firecrawl.scrape.ainvoke(url="https://example.com")

Search the web, discover a site’s URLs, and read one page. Firecrawl returns markdown rather than HTML, which is why it appears in an agent stack at all — the work of turning a rendered page into something a model can read happens on Firecrawl’s side. All three tools are POST. There is no GET in this pack: the option surface is large enough that Firecrawl takes it in a body even for what reads like a query.

Authenticating

This pack takes an API key in Authorization, and configure() is optional when $FIRECRAWL_API_KEY is set. There is no authorization server, no consent screen and no refresh — API keys is the whole story. The key is prefixed fc-… and goes out as a bearer token.

The client

api_key_tool_factory is the whole client: a thin wrapper over httpx that attaches your key and these endpoint constants to each request. firecrawl-py does not enter your dependency tree.

import os

from charter import Envelope, api_key_tool_factory

api_key = os.environ["FIRECRAWL_API_KEY"]

firecrawl_api_client = api_key_tool_factory(
    base_url="https://api.firecrawl.dev/v2/",
    api_key_headers={"Authorization": f"Bearer {api_key}"},
    body_format="json",
    query_format="repeat",
    body_case="camel",
    query_case="camel",
    path_case="snake",
    envelope=Envelope(ok_field="success", error_field="error"),
)

import os

from charter.packs import firecrawl

firecrawl.configure(api_key=os.environ["FIRECRAWL_API_KEY"])

# The base URL, the casing, the envelope and the pagination are
# already declared. 43 tools, ready to hand to a model:
tools = firecrawl.TOOLS

Paging through a list

A cursor belongs to the tool that returns it, so it is declared on that tool’s builder call:

firecrawl_pagination.py

activity = firecrawl_api_client(
    name="activity",
    args_schema=ActivityListRequest,
    method="GET",
    url_template="team/activity",
    pagination=Pagination(
        cursor_field="cursor",
        cursor_param="cursor",
        more_field="has_more",
    ),
)

Pagination is declared on activity. The other 42 take no cursor.

The base URL pins /v2/. Firecrawl versions its API in the path, so moving to a later version is a deliberate edit to firecrawl.BASE_URL rather than something that happens to you.

Tools

Each is a Tool, called with ainvoke as in the snippet above. The name links to its parameters, its response and what it costs.

SearchsearchPOSTSearch and optionally scrape web results.search_feedbackPOSTSubmit feedback for a prior search job to improve future results.MapmapPOSTDiscover and list all URLs of a website starting from a base URL.ScrapescrapePOSTScrape a single URL and optionally extract information.scrape_statusGETGet the status of a scrape job by job ID.scrape_interactPOSTExecute code in the browser sandbox associated with a scrape job.scrape_interact_stopDELETEStop the interactive browser session associated with a scrape job.Batchbatch_scrapePOSTScrape multiple URLs in one batch job.batch_scrape_statusGETGet the status and results of a batch scrape job.batch_scrape_cancelDELETECancel a running batch scrape job.batch_scrape_errorsGETGet per-URL errors from a batch scrape job.Interactinteract_createPOSTCreate a browser sandbox interact session for code execution.interact_executePOSTExecute Python, Node, or bash code in an interact session.interact_listGETList browser sandbox interact sessions for the authenticated team.interact_deleteDELETEDelete an interact session and stop billing for it.Researchresearch_papers_searchGETSearch the research paper index with natural-language queries.research_paper_getGETInspect metadata or read passages from a research paper.research_similar_papersGETFind related papers by semantic intent and structural mode.Developerdeveloper_searchGETSearch Firecrawl docs, issues, pull requests, and repository readmes.CrawlcrawlPOSTRecursively crawl a website and scrape each discovered page.crawl_statusGETGet the status and results of a crawl job.crawl_params_previewPOSTPreview crawl parameters generated from a natural language prompt.crawl_cancelDELETECancel a running crawl job.crawl_errorsGETGet per-URL errors from a crawl job.crawl_activeGETList all active crawl jobs for the authenticated team.ExtractextractPOSTExtract structured data from one or more URLs using an LLM.extract_statusGETGet the status and results of an extract job.Monitormonitor_createPOSTCreate a scheduled monitor for scrape, crawl, or search targets.monitor_listGETList monitors for the authenticated team.monitor_getGETGet a monitor by ID.monitor_updatePATCHUpdate a monitor’s schedule, targets, or status.monitor_deleteDELETEDelete a monitor.monitor_runPOSTQueue an immediate monitor check outside the schedule.monitor_checks_listGETList checks for a monitor.monitor_check_getGETGet a monitor check with optional page-level results.AccountactivityGETList recent API activity for the authenticated team.credit_usageGETGet remaining credits and billing period for the authenticated team.historical_credit_usageGETGet historical credit usage by billing period.token_usageGETGet remaining extract tokens for the authenticated team.historical_token_usageGETGet historical extract token usage by billing period.queue_statusGETGet metrics about the team’s scrape queue.threat_protection_getGETGet the team’s threat protection policy.threat_protection_updatePUTUpdate the team’s threat protection policy.

What each tool is for

search is the one to reach for on a factual question, a current event, or anything that benefits from real-time results. It searches web, image and news sources, and scrape_options makes it return page content rather than links alone — one call instead of a search followed by a scrape per result. map discovers a site’s URLs from a base URL, optionally filtered by a search term. It is how an agent finds the right page before reading it. scrape reads one URL. formats decides what comes back — markdown, HTML, a screenshot, or structured JSON extracted against a schema you supply.

Gotchas

scrape has thirty-odd options, and they cost context

formats, only_main_content, include_tags, exclude_tags, actions, proxy, location, wait_for and the rest are all on the schema the model fills in. If your agent only ever wants markdown of the main content, narrow the tool with Mode rather than trusting a prompt to leave the others alone.

timeout is Firecrawl's, not Charter's

Every tool here has a timeout field in its schema, which is how long Firecrawl will spend on the job. Charter’s own client timeout is tool.timeout — 20 seconds by default — and it is the smaller of the two that decides when a call gives up. Raise both, or neither.

Nothing here pages

search and map cap results with limit rather than handing back a cursor, so no tool declares a Pagination. Ask for more, not for the next page.

No rate-limit documentation is declared

quota_doc_url is unset on this pack, so the wire table has no rate-limit row. Firecrawl’s limits are a property of your plan; the account dashboard is where they are stated.

Responses come back untrimmed

No tool here has a response handler, deliberately: the payload is the page content, and there is nothing infrastructural to project away. A scrape of a long page is a long response, and only_main_content is the lever.

The API-key factory — what an API-key pack does not have
The mode system — narrowing a wide option surface

OAuth packs

API-key packs

Authenticating

The client

Paging through a list

Tools

What each tool is for

Gotchas

​Authenticating

​The client

​Paging through a list

​Tools

​What each tool is for

​Gotchas

​Related

Authenticating

The client

Paging through a list

Tools

What each tool is for

Gotchas

Related