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

# pi-websearch

Point pi-websearch's tavily backend at SpecStream with one websearch.json file, and the pi agent's web\_search tool answers from the SpecStream Search API at $1 per 1,000 searches of up to 10 results.

[SpecStream for pi-websearchCoding agents](https://specstream.ai/integrations/pi-websearch.md)

## What you need

-   The pi coding agent.
-   A SpecStream API key. New accounts start with $10 of credit, no card. [Get your key](https://specstream.ai/workspace/search?route=tavily&utm_source=pi-websearch&utm_medium=howto) on the Search API screen of your SpecStream workspace.

1.  1

    ## 1. Install pi-websearch

    pi-websearch is not on npm, so install it from its repository. Pi clones it and loads its `web_search` tool:

    Terminal

    ```bash
    pi install git:github.com/code-yeongyu/pi-websearch
    ```

2.  2

    ## 2. Write websearch.json

    pi-websearch reads the first of `.pi/websearch.json` in the current project, `~/websearch.json` and `~/.pi/websearch.json`. Put the file in your home folder so the key stays out of project repositories, and put your key in place of `YOUR_SPECSTREAM_API_KEY`:

    `baseUrl` is the whole search address, with `/search` at the end. pi-websearch posts to `baseUrl` exactly as written and adds no path, so `https://api.specstream.ai/tavily` alone would miss the search route.

    `"auto": false` makes SpecStream the only route. With `auto` on, the default, pi-websearch first tries the search tool built into models that have one (Claude, GPT 5, Grok and others), and SpecStream answers only when that fails.

    ~/.pi/websearch.json

    ```json
    {
      "backend": "tavily",
      "apiKey": "YOUR_SPECSTREAM_API_KEY",
      "baseUrl": "https://api.specstream.ai/tavily/search",
      "maxResults": 10,
      "auto": false
    }
    ```

3.  3

    ## 3. Check it in pi

    Start pi and run `/websearch status` to see its activation state. Then ask about something from this week. The search line in the TUI names `tavily` as the provider, and the results carry the title, URL and text of each page SpecStream found.

## What SpecStream answers

`https://api.specstream.ai/tavily/search` takes Tavily's request and answers in Tavily's shape: `results` with `title`, `url` and `content`, which pi-websearch's tavily backend reads. The key goes as a Bearer token, which is how pi-websearch sends `apiKey`.

Checked on November 12, 2026: the request pi-websearch builds for `tavily`, with `query`, `max_results` and `include_domains`, sent to this address, returned results from the domains asked for.

The Search API scores 97.9 F-score on all 1,000 SimpleQA Verified questions and 64.0 item F1 on all 200 WideSearch tasks. [Scores and method](https://specstream.ai/benchmarks.md).

## Domain filters

pi-websearch sends a call's `allowed_domains` as `include_domains` and `blocked_domains` as `exclude_domains`, and SpecStream applies both. `allowedDomains` and `blockedDomains` in the file set the same filters for every search.

## Keep DuckDuckGo as a backup

With a `providers` list, pi-websearch tries lower `priority` values first and moves to the next entry when one fails. This keeps the free DuckDuckGo HTML backend behind SpecStream:

## Cost

Each search through this address is $1 per 1,000 searches of up to 10 results, from your balance, with no quote and no approval. Each started block of 10 more results adds $0.0012 to a call, so keep `maxResults` at 10 unless you need more. pi-websearch asks for at most 20. A search that returns nothing costs nothing. Each reply carries `X-Balance-Cents`, your balance in cents after the call.

## Where the key lives

pi-websearch reads `apiKey` as written in the file. A project's `.pi/websearch.json` wins over the files in your home folder, so a project file without the key replaces SpecStream for that project. Give the key a spending limit under [Agents & API](https://specstream.ai/workspace/agents?tab=keys&utm_source=pi-websearch).

## More than search

For records with a source on every value, saved lists and monitors, add SpecStream's own Pi package as well. See [SpecStream in Pi](https://specstream.ai/docs/integrations/pi.md). Moving code that calls Tavily directly is covered in [moving from Tavily](https://specstream.ai/migrate/tavily.md).

## Disconnect

Delete `~/.pi/websearch.json`, and pi-websearch goes back to its defaults. Revoke the key under **API keys** in **Agents & API**. Questions go to [support@specstream.ai](mailto:support@specstream.ai).

## More

[SpecStream for pi-websearch](https://specstream.ai/integrations/pi-websearch.md) covers what it does in pi-websearch 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).