Skip to the page
Get started free

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

What you need

  • Free Clay running on your Cloudflare account, and a terminal in the free-clay folder.
  • A SpecStream account. Create one.

  1. 1. Create a SpecStream API key

    In SpecStream, open Agents & API, 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. 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
    npx wrangler secret put SPECSTREAM_API_KEY

  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
    {"q": "Who is the CEO of {{company}}? Give the full name."}

  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. 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 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: [email protected].

More

SpecStream for Free Clay covers what it does in Free Clay 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].