> SpecStream is the live web data engine for teams and agents. This is the Markdown copy of https://specstream.ai/docs/integrations/clay. Every page, with what SpecStream does and costs: https://specstream.ai/llms.txt # 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](https://specstream.ai/integrations/clay.md) ## 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](https://specstream.ai/signup?utm_source=clay). - A SpecStream API key, made in step 1. 1. 1 ## 1. Create an API key In SpecStream, open [Agents & API](https://specstream.ai/workspace/agents?tab=keys&utm_source=clay), 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 ## 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 ## 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 ```text 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 ## 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 ## 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 ```json { "q": "/Request", "requested_units": /Count, "confirm_max_cents": /Max cents, "idempotency_key": "/Key", "callback_url": "YOUR_CLAY_WEBHOOK_URL", "callback_on": "done" } ``` 6. 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 ```text https://api.specstream.ai/v1/capacity/requests//Key/rows ``` 7. 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. - `_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 means | What to do | | --- | --- | --- | | `reading` | SpecStream is reading the request and pricing it. | Read it again in a few seconds. | | `started` | The run started. `status` shows where it is. | Wait for the rows in the webhook table. | | `needs_edit` | SpecStream 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_maximum` | The 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. | | `failed` | The 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](https://specstream.ai/docs/billing.md) 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 [support@specstream.ai](mailto:support@specstream.ai). ## More [SpecStream for Clay](https://specstream.ai/integrations/clay.md) covers what it does in 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).