Clay

What your agents can doCopy Anchor Link

Helios agents use the Clay Public API. They search its endpoints and call the one they need, with your API key attached server-side.

• Find people at target accounts by job title and company size
• Look up a company and its firmographics by domain
• Run a Clay-managed or custom function on up to 100 records, such as finding work emails, and read the results
• Query a known Clay table with filters
• Search and count the runs of Clay Workflows (beta)
• Check the workspace's remaining credits

The Public API can't add rows to a Clay table or edit them. It can't list your tables or functions either, so give the agent the table ID or the function ID in the prompt. A table's ID is the part of its Clay URL after /tables/, such as t_0te9i4tZEHwc9hihBXu.

Clay manages webhooks, Signals, Audiences, and Workflow editing through its CLI and app, not the Public API, so agents can't use them.

Searches count toward the workspace's search quota, which is 100 results per 30 days on the Free plan. Functions use credits as they do in Clay.

AuthenticationCopy Anchor Link

See Integration authentication for how credentials are stored and injected.

Clay API KeyCopy Anchor Link

The Public API is available on every Clay plan, including Free. A key belongs to the Clay user who creates it and the workspace it was created in.

1. In Clay, open API and CLI in the left sidebar, under Orchestration. If your workspace has no API and CLI page, open Settings → Account → API keys (beta) instead.
2. On the API keys tab, click Add API key and enter a Name.
3. Under Scopes, keep Public API selected.
4. Click Add API key and copy the key. Clay shows it only once.
5. In Helios, choose Clay API Key, paste the key into Clay API Key, and save.

Clay's Scopes list can show these options:

Clay can't change a key's scopes after you create it. To change them, create a new key and enter it through Manage.

To let agents run a custom function, open the function in Clay, open Details, and enable API & CLI. Then give the agent its ID in the form function:t_....

Clay lists table queries as an Enterprise feature. Its help center says basic row reads work on every plan, but joins, ranges, and paging past 100 rows need Enterprise.

If you delete the key in Clay, create a new one and enter it through Manage.

TriggersCopy Anchor Link

Clay can start a Workflow in two ways, and you set up both by hand. Clay's Public API has no endpoint to create webhooks, so Helios can't register them for you.

Table is optional. It matches the table field of the request body, such as Inbound*. Case matters. Rows with a missing or non-text table field only start workflows that have no table filter.

routine_run.finished has no filters. Clay's delivery carries only the webhook's ID and the run's routine_run_id.

A connection has one secret, and both setups use it. If you use both, set the connection's secret to the Clay webhook's signing secret, and put the same value in the HTTP API column's header.

Set up an HTTP API column for row.sentCopy Anchor Link

HTTP API columns need a Clay Growth or Enterprise plan.

1. Save the Clay connection in Helios.

2. Open the connection, click Manage, and open Advanced Configuration. It's collapsed by default. Webhook Setup shows the webhook URL and the secret field.

3. Generate a long random secret, such as the output of openssl rand -hex 32. Enter it in the secret field under Webhook Setup and save. Do this before you add the column, because Helios rejects every request until the secret is set. If you also use a Clay webhook, use its signing secret instead.

4. In your Clay table, click Add enrichment, choose HTTP API, and set:

   • Method: POST.
   • Endpoint: the webhook URL from Webhook Setup.
   • Headers: x-helios-webhook-secret, set to the secret from step 3. To keep it out of plain text in the column, save it in an HTTP API (Headers) account with Select header account → + Add account.
   • Body: a JSON object with the columns the agent needs, and the table's name in table. Put each column reference in quotes, as Clay requires for text values.

   Copy Text

   {
     "table": "Inbound leads",
     "email": "/Email",
     "company": "/Company",
     "domain": "/Domain"
   }

5. Under Run settings, click Add run condition if the column should only send rows that are ready, such as rows with an email.

6. Run the column on one row to test it, then on the rest of the table. For new rows to be sent as they arrive, the column must run automatically. Check its run settings in Clay.

Clay doesn't sign HTTP API requests. Helios checks the x-helios-webhook-secret header on every request and rejects requests without the right secret.

Clay sends no delivery ID for HTTP API requests, so Helios processes every request separately. Sending the same row again can start another workflow run, even if its values are unchanged.

Set up a Clay webhook for routine_run.finishedCopy Anchor Link

A routine is a Clay function or a Clay Workflow. Clay notifies a webhook when a routine run finishes, but only for runs started with that webhook's ID.

You create Clay webhooks with the Clay CLI. Install it and sign in with clay login, as Clay's quickstart describes. Signing in needs Editor or Admin access to the workspace.

1. Save the Clay connection in Helios. Open it, click Manage, open Advanced Configuration, and copy the webhook URL from Webhook Setup.

2. Create the webhook with that URL:

   Copy Text

   clay webhooks create <webhook URL>

   Clay returns the webhook's id and its signingSecret. It shows the secret only once.

3. Enter the signingSecret in the secret field under Webhook Setup and save. If an HTTP API column already sends rows to this connection, change its x-helios-webhook-secret header to the same value.

4. Run clay webhooks test <id>. It should report "status": "success". Helios accepts the test delivery but doesn't start a run.

5. Pass the webhook's id as webhook_id when you start a run, with POST /routines/{routine_id}/run, POST /routines/{routine_id}/run-batch/start, or clay routines runs start --webhook-id. For runs that an agent starts, give the agent the ID in its prompt.

When the run finishes, Clay sends a delivery like this:

{
  "webhookId": "wh_abc123",
  "createdAt": "2026-06-16T17:50:00.000Z",
  "data": { "routine_run_id": "run_abc123" }
}

The agent reads the results with GET /routines/run/{routine_run_id}/results. For a batch run, GET /routines/run-batch/{routine_run_id}/results returns the status and a download link for the result file.

Clay signs each delivery with the HMAC-SHA256 X-Clay-Signature header, and Helios rejects deliveries without a valid signature. If Clay sends the same run's delivery again within 24 hours, Helios starts only one run. Clay doesn't guarantee delivery, so a finished run can go unreported.

Deleting the connection in Helios doesn't delete the Clay webhook. Remove it with clay webhooks delete <id>.

Check that it worksCopy Anchor Link

• The connection: after you save, the connection's status shows Connected. Error means the connection test failed. Open the connection to read the error.
• An HTTP API column:
  1. Add row.sent to a workflow with no filters.
  2. Run the HTTP API column on one row in Clay.
  3. Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.
• A Clay webhook:

  1. Run clay webhooks test <id> and check that it reports "status": "success".

  2. Add routine_run.finished to a workflow.

  3. Run a function on one item with the webhook's ID:

     Copy Text

     clay routines runs start function:t_... --input '{"items":[{"id":"test-1","inputs":{"domain":"clay.com"}}]}' --webhook-id <id>

  4. Check that a run starts when the function run finishes. Then open the connection in Helios and click Webhook events to see the event.

• Clay's side: the HTTP API column's cell shows Helios's response for that row. A working request returns {"message":"Webhook received"}. clay webhooks list shows each Clay webhook and its URL.

Common errorsCopy Anchor Link

LimitsCopy Anchor Link

Clay limits search results by plan. See Clay's search limits for your plan's allowance and reset schedule. Clay also rate-limits each workspace and answers 429 with a Retry-After header. See Clay's rate limits.