Knowledge & tools

Firecrawl tool

Firecrawl reads websites that ordinary fetching cannot. It runs the page's JavaScript and gets past most bot blocking, and it can go further than a single page: crawl a site, map its URLs, search, and watch pages for changes. One API key covers the lot, and the agent picks what to do from 47 actions.

When to reach for it

Most of the time an agent reads a page with the plain fetch-webpage tool, and that is the right thing: it is free, instant, and enough for ordinary pages. Firecrawl is the escalation. Give an agent both, and it can fall back when fetching returns an empty page or gets turned away.

Two cases where plain fetching loses and Firecrawl wins:

The page is built by JavaScript. Fetching returns the shell, with none of the text a person sees in a browser. Firecrawl renders the page first, so the agent gets the real content.
The site blocks bots. Some sites refuse anything that isn't a browser. Firecrawl gets past most of that.

Assigning both tools costs nothing extra. Firecrawl spends credits only when it is actually called, so the usual setup is fetch-webpage for everyday reading with Firecrawl behind it for the pages that fight back.

What it can do

The agent chooses one action per call, and it picks from all 47 without you configuring anything. By area:

Scrape (2 actions) - read a single page and return its content.
Batch scrape (4) - read a list of URLs as one job.
Crawl (6) - follow links from a starting page to read a whole section or site.
Map (1) - list the URLs a site exposes, without reading them.
Search (2) - search the web, with results the agent can then read.
Research index (3) - search a shared index of scientific papers that Firecrawl maintains, open one paper for its authors, abstract and identifiers (or for the passages that best match a question), and follow the citation graph out to related work.
Agent (6) - give Firecrawl a question instead of a URL. Its own model reads across one or more pages and comes back with structured fields plus a sentence or two of prose. You can point it at specific URLs, describe the shape of answer you want, and cap what it may spend.
Interact (6) - drive a page before reading it. Two of the six act on a page that has already been scraped and take plain instructions, which is the cookie-wall or "load more" case. The other four open a standalone browser session driven by code rather than by language.
Monitor (8) - watch pages on a schedule and report what changed. Creating a monitor leaves something running; see credits.
Parse (1) - turn a document into text.
Team usage (8) - read the Firecrawl account's own credit and usage figures.

The research index is worth a word of honesty: it indexes scientific papers, so it earns its keep on a research or technical agent and is dead weight on a front-desk or sales one. If your agent will never be asked about a paper, nothing is lost by it sitting there unused.

Because the tool runs outside the model's turn, a Firecrawl configuration can also be wired as a post-call action hook, for instance re-reading a page after every call and mailing on what changed.

Long jobs finish on a later turn

Crawling a site, batch scraping and the agent actions can take a while, so they do not block the conversation. They start the work and hand back a job id, and the agent checks that id again on a later turn. In practice this means a crawl you asked for in one message can be answered two or three messages later, and the agent will say so while it waits.

That is worth knowing before you judge an agent as slow or stuck: a scheduled run asked to crawl a site is doing exactly this, and the run's trace shows the polling as it happens. A plain scrape is not affected - those return on the same turn, and Firecrawl caps them at 120 seconds.

Only those three wait. Search, map and the research index all answer immediately, and a scrape hands the page straight back. Two others hand back an id that looks like a job id but isn't one: opening a browser session gives you a session that is live right away, and creating a monitor gives you a monitor that now exists and runs on its own schedule.

Getting a key

Sign up at firecrawl.dev. The free tier needs no card.
Open API Keys and create a key. Firecrawl keys start with fc-.
Copy it into the API key field in Hania and save.

The free tier gives you 1,000 credits a month, which is enough to try the tool properly and enough for light everyday use.

What it costs in credits

Firecrawl bills its own credits, not Hania usage, so this is about your Firecrawl plan rather than your Hania bill. The shape of it:

One credit per page read, as the base rate.
Structured extraction adds four credits per page. That is the mode where the agent asks for specific fields back as JSON rather than the page text, so a page read that way costs five.
The enhanced proxy is free. It is what does the heavy unblocking, it is the default, and it adds nothing to the credit cost, so there is no reason to avoid it.
The research index is free. Searching papers, opening one and walking its citations all cost nothing.
Browser sessions bill by the minute, between two and seven credits a minute with a minimum of two. A session that is opened and never closed keeps billing until it times out on its own, which by default takes five minutes.
The agent actions don't follow the per-page rule. What they cost depends on how much reading the question turns out to need, so you cannot predict it from a page count. They are also still in preview, with a few free runs a day, which means today's bill is a poor guide to tomorrow's. Cap it per call if that matters to you: the agent can be told a credit ceiling for the run.

A crawl reads many pages, so it spends a credit for each one. If you are on the free tier and want an agent crawling regularly, watch the monthly figure - the team usage actions let the agent read it back for you.

One thing that is genuinely Firecrawl's bill and not yours: the agent actions run Firecrawl's own model, paid for in Firecrawl credits. None of that reasoning passes through Hania, so on your Hania usage it looks like one ordinary tool call however much thinking went into it.

A monitor keeps spending after everyone has stopped asking. Every other action costs something when it is called and nothing when it isn't. A monitor is different: once created it runs on its schedule whether or not anybody ever looks at the result, and the agent can create one on its own if it has the action. The shortest interval is five minutes, so a monitor over a handful of URLs can work through a free tier's whole 1,000 credits a month with no further tool calls at all. Firecrawl reports an estimated monthly cost when the monitor is created, and a once-daily monitor on a single URL came back at 30 credits a month. To see what is running, ask the agent to list your monitors; to stop one, ask it to delete that monitor.

Field reference

API key (required, secret) - your Firecrawl key, from firecrawl.dev under API Keys. Starts with fc-. Stored encrypted and never returned.
Base URL (optional) - leave blank to use Firecrawl's cloud. Set it only if you run a self-hosted Firecrawl instance, in which case it points at yours, for example https://api.firecrawl.dev/v2 in the same shape.

Troubleshooting

"401 Unauthorized: Invalid token" - the key is wrong, was truncated when pasted, or has been revoked. Create a new one and retype it. Editing the configuration without retyping the key keeps the stored one.
A 402 - the Firecrawl plan is out of credits. Nothing is wrong with the setup; top up or wait for the monthly reset.
"Rate limited, retry after N seconds" - the free plan caps some families of action at roughly six requests a minute. The agent backs off and retries, so this usually costs time rather than the answer.
A 403 on a threat-protection action - those are an enterprise feature. A clean 403 there is the expected answer on any other plan, not a misconfiguration.
A site that never works - Firecrawl keeps its own blocklist, and a handful of sites are on it permanently. No key, plan or setting gets past that one, so treat those as out of reach rather than something to debug.
A validation error naming a field - Firecrawl rejected the request the agent built. The agent usually corrects itself and calls again, so these tend to flash past in a trace before the call succeeds.

Safety in autonomous runs

Like any tool, Firecrawl carries a safety classification (read-only / destructive / sends-data-externally) that governs scheduled or triggered runs. A new configuration is created read-only, with destructive and sends-data-externally both off, matching the plain fetch-webpage tool it stands in for.

Read-only describes the configuration rather than every single action. Most of the 47 do nothing but read; seventeen do more than that, and it is worth knowing what they are. They start or cancel a job, create, change or delete a monitor, open, drive and close a browser session, upload a document to be parsed, and change the account's threat-protection policy. None of them touches your own data. Everything they create lives on your Firecrawl account, which is exactly why the configuration ships with destructive off. The one that outlives the conversation is a monitor, and that is a credit question rather than a safety one.

Sends-data-externally being off is deliberate rather than an oversight. That flag asks the agent to name its destination in the task goal before an autonomous run may send anything, which is the right guard for email or an outbound API. Firecrawl's destination is a URL it was asked to read, so switching the flag on would block any scrape of a page the goal didn't name in advance - in other words it would stop the agent doing the one thing the tool is for.

If you want a person in the loop anyway, the finer lever is per-tool approval on the agent: assign the tool with Approval set to Always and every call pauses for someone to approve, edit or deny it. Interactive chat is never gated by the classification flags.

Security

The key is stored AES-encrypted at rest and is never returned by the API - the console shows only whether a key is set. Editing a configuration without retyping the key preserves the stored one, so you have to retype it to replace it. To revoke access, delete the key in Firecrawl under API Keys; it stops working everywhere at once.

One thing worth remembering about any tool that reads the open web: what comes back is somebody else's text, and an agent reading it should treat it as information rather than instruction. Hania's agents are built that way, but it is a good reason to keep write tools and read tools separately scoped on an agent that crawls widely.