> SpecStream is the live web data engine for teams and agents. This is the Markdown copy of https://specstream.ai/docs/integrations/dzhng-deep-research. Every page, with what SpecStream does and costs: https://specstream.ai/llms.txt

# deep-research (dzhng)

deep-research by dzhng reads one setting for its search address, `FIRECRAWL_BASE_URL`. Set it to `https://api.specstream.ai/firecrawl` and put your SpecStream key in `FIRECRAWL_KEY`, and every search of a research run goes to the SpecStream Search API. You change no code.

[SpecStream for deep-research (dzhng)Agent frameworks & builders](https://specstream.ai/integrations/dzhng-deep-research.md)

## What you need

-   deep-research cloned from `github.com/dzhng/deep-research`, with Node.js and an OpenAI key or another model set up as its README shows.
-   A SpecStream API key. New accounts start with $10 of credit, no card. [Create an account](https://specstream.ai/signup?utm_source=dzhng-deep-research).

1.  1

    ## 1. Get a SpecStream API key

    [Get your key](https://specstream.ai/workspace/search?route=firecrawl&utm_source=dzhng-deep-research&utm_medium=howto) on the Search API screen of your SpecStream workspace. deep-research sends it as a Bearer token, the way it sends a Firecrawl key.

2.  2

    ## 2. Set two lines in .env.local

    deep-research reads its settings from `.env.local` in the repository folder. Put your SpecStream key in `FIRECRAWL_KEY`, and remove the `#` in front of `FIRECRAWL_BASE_URL` and set it to the SpecStream address. Leave `OPENAI_KEY` and the model lines as they are.

    Write the address without `/v1`. The Firecrawl SDK the tool installs, `@mendable/firecrawl-js` 1.16.0, adds `/v1/search` to it.

    .env.local

    ```bash
    FIRECRAWL_KEY="YOUR_SPECSTREAM_KEY"
    FIRECRAWL_BASE_URL="https://api.specstream.ai/firecrawl"
    # FIRECRAWL_CONCURRENCY="2"
    
    OPENAI_KEY="your_openai_key"
    ```

3.  3

    ## 3. Run a research

    Start the tool and answer its prompts: the query, the breadth (default 4), the depth (default 2) and the follow-up questions. With Docker, the same `.env.local` is used: `docker compose up -d`, then `docker exec -it deep-research npm run docker`.

    The report is saved as `report.md`, or `answer.md` in answer mode, with the visited URLs listed at the end.

    Shell

    ```bash
    npm install
    npm start
    ```

4.  4

    ## 4. Check the calls

    Each search of the run is in the request log of your SpecStream workspace, with the Firecrawl route as its endpoint. Each charged reply carries an `X-Balance-Cents` header with your balance in cents.

5.  5

    ## 5. Or get the whole report in one call

    If you want the report and not the loop, SpecStream writes it. `POST /v1/research` takes the question in plain words and answers `202` with the report's `id`. Read `GET /v1/research/{id}` until `status` is `completed`. `report.content` is the text with `[1]` markers, `report.citations` gives each cited sentence its page, read time and passage, and `report.sources` lists every page read.

    `depth` is `quick`, `standard` (the default) or `deep`: $0.10, $0.30 or $1.00 a report. No OpenAI key is needed for this call. [The research docs](https://specstream.ai/docs/research.md) have every field.

    Shell

    ```bash
    curl -X POST https://api.specstream.ai/v1/research \
      -H "Authorization: Bearer YOUR_SPECSTREAM_KEY" \
      -H "Content-Type: application/json" \
      -d '{"input": "What changed in EU battery recycling rules this year?", "depth": "quick"}'
    ```

## What deep-research sends

-   `src/deep-research.ts` creates one Firecrawl client with `apiKey` from `FIRECRAWL_KEY` and `apiUrl` from `FIRECRAWL_BASE_URL`. When the second is empty, the SDK calls `https://api.firecrawl.dev`.
-   Each generated query is one `firecrawl.search` call: `POST /v1/search` with `limit` 5, a `timeout` of 15000 and `scrapeOptions` asking for `markdown`. The tool makes no separate scrape call.
-   SpecStream answers in Firecrawl's v1 shape: `data[]` with `url`, `title`, `description` and `markdown`. The tool reads `url` for the source list of the report and `markdown` for the learnings its model extracts.
-   In SpecStream's answer, `markdown` holds the text found for the query on each result, a passage and not the whole page. To read a whole page, call the [Extract API](https://specstream.ai/extract-api.md) at $0.80 per 1,000 pages.

## Cost of a run

Each search through the Firecrawl address is one Search API call at $1 per 1,000 searches of up to 10 results, the fast tier every drop-in address runs on. The tool asks for 5 results, so every search is in that price.

The number of searches follows from breadth and depth. Each level halves the breadth and rounds up. With the defaults, breadth 4 and depth 2, a run sends 4 searches, then 2 more for each of them: 12 searches, $0.012. Breadth 10 and depth 3 is 10, then 50, then 150: 210 searches, $0.21. The model calls are paid to your model provider and are the larger part of a run. New accounts start with $10 of credit, no card. [Balance and billing](https://specstream.ai/docs/billing.md) has the details.

## Three ways to run the search step

| Setup | What you change | What you pay for search |
| --- | --- | --- |
| SpecStream address | `FIRECRAWL_KEY` and `FIRECRAWL_BASE_URL` in `.env.local` | $1 per 1,000 searches of up to 10 results |
| Firecrawl's own API (the default) | `FIRECRAWL_KEY` only | Firecrawl's plan |
| Self-hosted Firecrawl | `FIRECRAWL_BASE_URL="http://localhost:3002"` and a Firecrawl server you run | Your own server, and the search backend you give it |
| SpecStream research report | One `POST /v1/research` call, no deep-research loop and no OpenAI key | $0.10, $0.30 or $1.00 a report |

## Concurrency

The tool runs 2 searches at once by default. The code reads `FIRECRAWL_CONCURRENCY` (`Number(process.env.FIRECRAWL_CONCURRENCY) || 2`). The README names `CONCURRENCY_LIMIT`, which the code does not read, so set `FIRECRAWL_CONCURRENCY`. A higher number makes a wide run finish sooner. If SpecStream answers `429` with `Retry-After`, the account used its calls for the minute: lower the number. Nothing is charged for that reply.

## If searches fail

-   `401`: the key did not reach SpecStream. Check `FIRECRAWL_KEY` in `.env.local`, and that the file is in the repository folder.
-   A `404` or `405`: check that `FIRECRAWL_BASE_URL` is `https://api.specstream.ai/firecrawl`, with no `/v1` and no trailing slash.
-   A report with no sources: the tool logs each failed query and goes on, so read the terminal output for the error of the first search.
-   `429` with `Retry-After`: wait that many seconds, or set `FIRECRAWL_CONCURRENCY="1"`.

## Other ways to use SpecStream

For a list with the same facts on every row, ask an assistant connected to the [SpecStream MCP server](https://specstream.ai/docs/mcp.md) at `https://api.specstream.ai/mcp`. The [Firecrawl migration page](https://specstream.ai/migrate/firecrawl.md) lists every Firecrawl parameter the address applies. For the web version of this tool, see the [Deep Research Web UI guide](https://specstream.ai/docs/integrations/deep-research-web-ui.md).

## Switch back

Put the `#` back in front of `FIRECRAWL_BASE_URL` and your Firecrawl key back in `FIRECRAWL_KEY`. The tool calls `https://api.firecrawl.dev` again on the next run.

## More

[SpecStream for deep-research (dzhng)](https://specstream.ai/integrations/dzhng-deep-research.md) covers what it does in deep-research (dzhng) on one page. Every other tool has its guide in [Connect your tools](https://specstream.ai/docs/integrations.md). You see the most a request can cost before it starts, and the matches are paid from your balance. [Billing](https://specstream.ai/docs/billing.md) has the details. For help, email [support@specstream.ai](mailto:support@specstream.ai).