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

# Free Clay

Add SpecStream to Free Clay as an HTTP API column, and each row of a table gets an answer from the live web with the page it was read from. The same key gives Free Clay agents SpecStream's tools over MCP.

[SpecStream for Free ClayOutreach & sales](https://specstream.ai/integrations/free-clay.md)

## What you need

-   Free Clay running on your Cloudflare account, and a terminal in the `free-clay` folder.
-   A SpecStream account. [Create one](https://specstream.ai/signup?utm_source=free-clay).

1.  1

    ## 1. Create a SpecStream API key

    In SpecStream, open [Agents & API](https://specstream.ai/workspace/agents?tab=keys&utm_source=free-clay), choose **API keys**, then **Create API key**, and set a total spending limit. The key needs the `finds:spend` scope to search and read pages.

2.  2

    ## 2. Store the key in Free Clay

    In the `free-clay` folder, run the command below. Wrangler asks for the value and sends it to Cloudflare, so the key never sits in the app, the database or the repo.

    Then open **Settings**, **Keys** in Free Clay, type `SPECSTREAM_API_KEY` and select **Add key name**.

    Terminal

    ```bash
    npx wrangler secret put SPECSTREAM_API_KEY
    ```

3.  3

    ## 3. Add an HTTP API column

    In a table, select **Add column**, then **HTTP API**. Set **Method** to `POST` and **URL** to `https://api.specstream.ai/v1/web-search`.

    Select **Add header**, with the name `Authorization` and the value `Bearer {{secret:SPECSTREAM_API_KEY}}`. Free Clay fills the key in at call time and never shows it.

    In **Body**, write the question for each row, with a column's key in double braces. Free Clay escapes column values for JSON.

    Body

    ```json
    {"q": "Who is the CEO of {{company}}? Give the full name."}
    ```

4.  4

    ## 4. Map the reply to columns

    Set **Value for this column (JSON path)** to `data.answer.value`. Under **More columns from the response**, select **Add output** and map `data.answer.page` to a column named `Source`.

    In **Your cost per call ($)**, enter the price of one search: $5 per 1,000 searches, divided by 1,000. Free Clay counts it against each run's budget. Select **Add column** to save.

5.  5

    ## 5. Run it

    Open the column's run menu and choose **Run empty rows**. Set **Stop when this run has spent ($)**, then run. Free Clay reserves the worst case before the first call and stops before it would go over. Cells fill as the answers come back.

## What comes back

SpecStream answers `{"data": {...}}`. These paths fit a column:

-   `data.answer.value`: the answer as the page prints it. It is null when no result prints one, and Free Clay shows the cell as no result.
-   `data.answer.page`: the page the answer was read from, and `data.answer.seen_at`: when it was read.
-   `data.sources[0].url` and `data.sources[0].title`: the top search result.
-   `data.price_usd`: what the call cost.

## Read each company's site

A second HTTP API column reads a page with the Extract API. Use `POST`, the URL `https://api.specstream.ai/v1/extract`, the same header, and the body `{"urls": ["{{website}}"]}`.

Set the value path to `data.results[0].text` for the page's main text, without menus, footers and ads. Add an output for `data.results[0].emails[0].address`, the first email address the page carries, also one only its markup shows.

Each page read costs $0.80 per 1,000 pages, and a page with no text is not charged.

## Give an agent SpecStream's tools

In **Agents**, open an agent or select **New agent**. Under **MCP servers**, select **Add MCP server**: name `specstream`, URL `https://api.specstream.ai/mcp`, and `SPECSTREAM_API_KEY` as the key name. Free Clay sends the key as a Bearer token. Select **Save**.

The agent can then call `search_web` for one fact, `read_pages` for the text of known pages, and the Deep Search tools for a full list in structured rows. Deep Search work starts only when the agent approves its quoted maximum, and the key's spending limit bounds everything the agent spends, so set that limit to what the agent may spend.

## Cost

The Search API costs $5 per 1,000 searches of up to 10 results, and a search that returns no results costs nothing. The Extract API costs $0.80 per 1,000 pages. Both come out of your balance, with no quote and no approval. Deep Search is priced per delivered row, with the maximum quoted before the run. New accounts start with $10 of credit, no card. [Balance, quotes, and billing](https://specstream.ai/docs/billing.md) has the details.

## If a cell shows an error

Free Clay shows `HTTP` and the status in the cell.

-   `SPECSTREAM_API_KEY is not set`: run `npx wrangler secret put SPECSTREAM_API_KEY`, then reload.
-   `HTTP 401`: the key is unknown, expired or revoked.
-   `HTTP 402`: the balance is empty, or the call would pass the account's monthly spending limit.
-   `HTTP 403`: the key has no `finds:spend`, or the call would pass the key's spending limit.
-   `HTTP 503`: search is busy. Run the errored rows again after the wait in `Retry-After`. Nothing was charged.

## Disconnect

Delete the columns, or forget `SPECSTREAM_API_KEY` under **Settings**, **Keys**, then revoke the key under **Agents & API** in SpecStream. Questions: [support@specstream.ai](mailto:support@specstream.ai).

## More

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