Skip to the page
Get started free

Clay

Call SpecStream from a Clay table with your own SpecStream API key, through Clay's HTTP API enrichment. Ask the Search API one question per row, or ask Deep Search for a list and get its rows in a Clay webhook table.

SpecStream for ClayOutreach & sales

What you need

  • A Clay plan that includes the HTTP API enrichment.
  • A SpecStream account. New accounts get $10 of credit on sign-up, no card. Create one.
  • A SpecStream API key, made in step 1.

  1. 1. Create an API key

    In SpecStream, open Agents & API, choose API keys, then Create API key, and name the key Clay.

    The Search API needs Authorize paid work. Deep Search also needs Read saved requests, Create and edit requests, Prepare work and follow-ups, and Read results and their sources. Under Authorize paid work, give the key a Total spending limit. Before the key can start a run, set your account's own spending limit in Settings, under Usage and billing.

    The key is shown once, so copy it before you close the dialog.

  2. 2. Save the key in Clay

    In a table, click Add enrichment, search for HTTP API, and open Configure. Click Select header account, then + Add account.

    Under API Request Headers, add Authorization with the value Bearer YOUR_SPECSTREAM_KEY, and Content-Type with the value application/json. Name the account SpecStream and click Save. Every HTTP API column in the workspace can then use it.

  3. 3. Ask one question per row

    Add a text column named Company. Add an HTTP API enrichment, choose the SpecStream header account, and fill it in as below. Type / to insert a column.

    Click Test on one row, then run the column. data.answer.value is the answer, data.answer.page is the page it was read from, and data.answer.seen_at is when it was read. When no result prints an answer, data.answer is empty and data.sources lists the results read.

    Each search is $5 per 1,000 searches of up to 10 results, with no quote and no approval.

    HTTP API column
    Method: GET
    Endpoint: https://api.specstream.ai/v1/web-search
    Query string: q = Who is the chief executive of /Company?
    Field paths to return: data.answer.value, data.answer.page, data.answer.seen_at, data.price_usd

  4. 4. Make a webhook table for the rows

    Deep Search finds every match for a request and sends the rows to Clay when the run ends. In a workbook, click + Add at the bottom, search for Webhooks, and click Monitor webhook. Copy its URL.

    Leave the webhook without an authentication token, because SpecStream sends none.

  5. 5. Start a request with a maximum price

    Make a table with four columns: Request (text), Count (number, 1 to 500), Max cents (number, the most the request may cost) and Key (text, 8 to 128 characters, new for each request).

    Add an HTTP API enrichment named Start with the method POST, the SpecStream header account, the endpoint https://api.specstream.ai/v1/capacity/requests, and the body below. Put quotes around text columns and none around number columns, and paste your webhook URL in callback_url. Set Field paths to return to data.state and data.message, and leave Rate limiting empty.

    Try it with the Request Cybersecurity software companies in Germany with 50 to 200 employees, with their website and headquarters city, a Count of 25, and Max cents of 500.

    Body of the Start column
    {
      "q": "/Request",
      "requested_units": /Count,
      "confirm_max_cents": /Max cents,
      "idempotency_key": "/Key",
      "callback_url": "YOUR_CLAY_WEBHOOK_URL",
      "callback_on": "done"
    }

  6. 6. See the price and approve it

    Start answers at once with the state reading. SpecStream then reads the request and prices it, and starts the run only when the price is at or below Max cents. Above it, nothing runs.

    To follow a request, add an HTTP API column named Status with the method GET and the endpoint below, with the Key column inserted after requests/. Under Conditional runs, run it only when Start is not empty. Set Field paths to return to data.state, data.read_back, data.maximum_cents, data.message, and data.done. Reading it costs nothing.

    To see the price before anything runs, set Max cents to 1. The state is then above_maximum, maximum_cents is the price, and read_back is how SpecStream read the request. To approve that price, set Max cents to it, give the row a new Key, and run Start again. The webhook table also gets a row each time a request ends without a run.

    Endpoint of the Status column
    https://api.specstream.ai/v1/capacity/requests//Key/rows

  7. 7. Make one Clay row per result

    When the run ends, SpecStream posts the rows to the webhook table, so no row in Clay waits on a running list. A large result arrives in parts of at most 90 KB, each as its own webhook row.

    In the webhook table, click Exports, then Send table data. Pick the destination table, choose Send row for each item in a list, select flat_rows, and click Save. In the destination table, click a cell, hover over a field, and click Add to column.

    For a request about people, add "one_row_per": "people" to the Start body, and each person arrives as a row of their own.

What arrives

Each item of flat_rows is one result as flat fields.

Source URL and read time on every value.

  • id, position, and list_link, which opens the list in your SpecStream workspace.
  • One field per column, named the way the list names it.
  • <field>_source beside each field: the page that value was read from.
  • source_url and checked_at: the page of the fact that put the result in the list, and when it was read.
  • rows holds each result in full, with every value's page and read time.

What the state says

Status reads data.state. A request that ends without a run sends the same state to the webhook table.

`state`What it meansWhat to do
readingSpecStream is reading the request and pricing it.Read it again in a few seconds.
startedThe run started. status shows where it is.Wait for the rows in the webhook table.
needs_editSpecStream needs a clearer request. read_back shows how it read it.Add the place or what every result must meet, then start it again with a new key.
above_maximumThe price is above your maximum, and nothing ran. maximum_cents is the price.Raise the maximum or ask for fewer results, then start it again with a new key.
failedThe run did not start. message says why, such as the key's spending limit.Fix what message names and start it again with the same key.

Cost

Searches and rows are paid to SpecStream from your SpecStream balance. Reading a request, pricing it, and reading Status cost nothing. A search is $5 per 1,000 searches of up to 10 results. Each matching row costs 5¢, 15¢ or $1, depending on how much the row needs, plus 5¢ for a person's email and 15¢ for a phone. A run never costs more than the maximum you set, and a run that finds nothing costs nothing. Clay bills for its own plan. Balance, quotes, and billing has the details.

Disconnect

Delete the HTTP API columns, then delete the SpecStream header account under Settings, then Connections. To end access, revoke the key under API keys in Agents & API. Rows already in Clay stay there. Questions go to [email protected].

More

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