Skip to main content

Connect Clay

Clay lets a Task find people and companies, run enrichment routines and inspect results. The connector uses Clay's native Public API, with a personal API key tied to your Clay user and workspace.

Add a credential​

  1. Sign in to your own Clay workspace. Review the workspace's plan and available credits before running searches or enrichment.
  2. In Clay, open API and CLI → API keys and create a key with Public API selected under Scopes. A key scoped only to Account prioritization cannot perform these Public API checks. Keep it private. See Clay's authentication guide.
  3. In qbash, open Connectors → Clay and add a credential. Give it a name and paste the key into API Key.
  4. Save the credential. qbash encrypts the key and checks its format. Saving does not contact Clay or prove that the key works.
  5. Add Clay to your Task and explicitly select the saved credential. Start with the read-only check below.
identity = qbash.integrations.clay.get_me()
qbash.output(identity)

Clay shows the full secret when a key is created and masks it in the key list afterward. Copy the full secret directly into qbash. The masked prefix and suffix will not authenticate. Clay’s current key-edit dialog changes the name only. To correct a scope mismatch, create a replacement with Public API selected and update the qbash credential.

When editing a credential, leave API Key blank to keep the saved key. Paste a replacement only when you intend to change it.

Search and enrich​

Fetch get_search_reference() before composing a query. create_search(query=...) returns a search_id. Call run_search(search_id=..., limit=20) to retrieve a page, then repeat only while has_more is true. This is a stateful iterator. A repeated call advances to the next page and can consume credits. There is no cursor and no automatic retry.

Use a known Clay-managed or custom function routine ID with run_routine(routine_id=..., items=[{"id": "row-1", "inputs": {"domain": "example.com"}}]). Adapt the input names to your function. Custom function IDs use function:t_.... The connector accepts 1–100 items per run and an optional existing webhook_id.

The returned routine_run_id identifies asynchronous work. Read it with get_routine_results(routine_run_id=...), using a delay and a bounded timeout between polls. During processing, data can be absent. Completed results may have a cursor: pass it on the next request until omitted. Check each item's status and error, because a complete run can contain failures. finished includes failed items. See Routines API.

For a small test, prepare one custom function in Clay with a known input and inspect its expected output there first. Use one synthetic item and approve its credit use before running it from qbash. Account creation, key creation and provider usage require the workspace owner's action.

Tables and workflow runs​

query_table(table_id=..., fields=["Domain"], limit=20) reads one page from a known table on an Enterprise plan. Get its ID from the Clay URL after /tables/. Cells retain their status, value and fields, so empty, pending and error cells remain distinct. Pass the returned cursor to read another page. Concurrent edits can cause repeated rows. The connector does not discover tables or expose filters, joins, sorting or aggregation. See Tables (Enterprise).

get_workflow_runs_reference() supplies the current beta query syntax. Use query_workflow_runs(query=...) for a select or count query. Responses retain Clay's fields and optional cursor. These beta endpoints can change.

Costs and limits​

get_credit_balance() reports remaining workspace credits and optional personal limits. Searches and routine runs can consume Actions and Data Credits. Plan limits can be lower than the API's maximum page size. A 402 reports a credit or plan limit. A 403 reports access or plan restrictions. A 429 includes numeric Retry-After seconds when supplied. Wait before retrying. See Rate limits.

Each method makes one request. A timeout or connection failure can leave a write's outcome unknown. Check provider state before repeating it.

The connector exposes ten native Public API methods in the SDK Reference. It does not proxy Clay's hosted MCP server. That separate service uses OAuth. Batch JSONL upload/download, structured-filter searches, advanced table queries, Audiences deletion, webhook management and CLI-only administration are outside this connector's scope. Live provider behavior requires verification with your selected key and plan.

Last updated on