Skip to the page
Get started free

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

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.

  1. 1. Get a SpecStream API key

    Get your key 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. 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
    FIRECRAWL_KEY="YOUR_SPECSTREAM_KEY"
    FIRECRAWL_BASE_URL="https://api.specstream.ai/firecrawl"
    # FIRECRAWL_CONCURRENCY="2"
    

    OPENAI_KEY="your_openai_key"

  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
    npm install
    npm start

  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. 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 have every field.

    Shell
    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 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 has the details.

Three ways to run the search step

SetupWhat you changeWhat you pay for search
SpecStream addressFIRECRAWL_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 onlyFirecrawl's plan
Self-hosted FirecrawlFIRECRAWL_BASE_URL="http://localhost:3002" and a Firecrawl server you runYour own server, and the search backend you give it
SpecStream research reportOne 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 at https://api.specstream.ai/mcp. The Firecrawl migration page lists every Firecrawl parameter the address applies. For the web version of this tool, see the Deep Research Web UI guide.

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) covers what it does in deep-research (dzhng) on one page. Every other tool has its guide in Connect your tools. You see the most a request can cost before it starts, and the matches are paid from your balance. Billing has the details. For help, email [email protected].