Clay

Clay

This connector uses the Clay Public API (https://api.clay.com/public/v0): searches of Clay's people and company database, runs of Clay functions (enrichment and research), queries of Clay tables, Workflow run search, credit balance and privacy deletion.

What it cannot do: the Public API has no endpoints to list tables or functions, create tables or write rows. Rows are still written to tables through a table's inbound webhook, and function and table ids are copied from the Clay app.

Setup

1. In Clay open API and CLI, tab API keys (https://app.clay.com/workspaces/~/api-and-cli?tab=api-keys) and create a key. The key acts as your user, with your workspace access.
2. Paste it into CLAY_API_KEY. It is sent in the clay-api-key header.
3. For custom functions, open the function in Clay, Details, and enable API access; copy its t_... id.

Check the key: clay_get_me returns the user and workspace; clay_get_credit_balance shows the credits left.

Search the GTM database

1. clay_get_search_query_reference once per session to learn the fields and grammar.
2. clay_create_search with a query such as select from companies where people.exists(is_current = true and job_title is_similar_to ("VP Sales")); keep the search_id.
3. clay_get_search_results with that id; it is a stateful iterator: each call returns the next page, call again while has_more is true. Search results count against the plan's result limits (free: 50 per search and 100 per 30 days; paid: 500 per request). Over a limit Clay answers 402 naming the limit.

Enrich with a function

1. clay_run_routine with the routine id (function:t_...) and up to 100 items {"id": "...", "inputs": {...}}. It spends credits.
2. clay_get_run_results with the routine_run_id: HTTP 202 and status: in_progress while running, then 200 with status: complete and data. Match results to inputs by id, not by order; a complete run can contain failed items. total and finished count the whole run, finished includes failures. Poll every few seconds, not in a tight loop.
3. clay_get_batch_run_results reads batch runs started from the Clay CLI; a finished batch returns result_url.

Tables (Enterprise): clay_query_tables with the table id from the table's URL (.../tables/t_...). Cells come back with a status: success (with value), empty, error (with error), or a pending state (running, queued, retry, rate_limited, awaiting_callback). Pass cursor back to page; a scan can return a row twice when it changes mid-scan, so deduplicate by id.

Workflows (beta): clay_get_runs_query_reference, then clay_query_workflow_runs to find runs and their status.

Privacy: clay_privacy_delete_people (installed switched off) deletes people from Audiences; try dry_run: true first, then follow the job with clay_get_privacy_deletion_status.

Paging: collections return data and a cursor while more pages exist; search iterators return data and has_more.

Errors: errors carry a message. 401/403: wrong key or no access; 402: search result limit reached; 404: unknown id, or a function without API access; 409/422: invalid request state or input; 429: workspace rate limit, wait for Retry-After seconds.