> ## Documentation Index
> Fetch the complete documentation index at: https://docs.r28.ai/charter/llms.txt
> Use this file to discover all available pages before exploring further.
# Firecrawl
> Search the web, map a site's URLs, and read a page as markdown.
```python firecrawl_example.py {7} theme={null}
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()`](/charter/charter/reference/configuration#configure) is optional when `$FIRECRAWL_API_KEY` is set.
There is no authorization server, no consent screen and no refresh — [API keys](/charter/charter/auth/api-key-tool-factory) is the whole story.
The key is prefixed `fc-…` and goes out as a bearer token.
## The client
[`api_key_tool_factory`](/charter/charter/reference/factories#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.
```python Without the pack theme={null}
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"),
)
```
```python With the pack theme={null}
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:
```python firecrawl_pagination.py theme={null}
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`](/charter/charter/reference/tool), called with
[`ainvoke`](/charter/charter/reference/tool#tool-ainvoke) as in the snippet above. The name
links to its parameters, its response and what it costs.
## 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
`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`](/charter/charter/boundary/mode-system) rather than trusting a prompt
to leave the others alone.
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.
`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.
`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.
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.
## Related
* [The API-key factory](/charter/charter/auth/api-key-tool-factory) — what an API-key pack does not have
* [The mode system](/charter/charter/boundary/mode-system) — narrowing a wide option surface