Skip to main content
Routines are the programmable way to run Clay logic. Through the Public API, you can run Clay-managed functions and custom functions from backend services, queue workers, internal tools, and custom apps. Use Clay-managed functions for common enrichment and research jobs. Use custom functions for team-specific Clay logic built in the Clay UI.

​
Run a function routine

Custom function routine ids use the format function:t_.... To start a run, call POST /routines/{routine_id}/run. Replace function:t_abc123 and the input names with your function’s routine id and inputs. Give each item an id you can use to match its result later.

​
Read the results

Use the returned routine_run_id to request the run’s results:
While the run is processing, the endpoint returns HTTP 202 with progress counters. There is no data array yet:
Repeat the GET request until it returns HTTP 200 with status: "complete". Use a delay between polls and a timeout appropriate for your application. For HTTP errors, follow the error handling and rate limit guidance rather than continuing to poll unchanged. Read individual results from data. Each item’s id matches an id you supplied in the run request. Check each item’s status: a completed run can contain failed items. For example, a function with a company_name output could return:
The keys inside result depend on your function’s outputs. Use item ids to associate results with inputs rather than relying on response order. finished counts finished items, including failures; it is not a count of successful results.

​
Retrieve every page

A completed run’s results can span multiple pages. If the response includes cursor, pass that value to the same endpoint to retrieve the next page:
Collect data from each page and continue with each returned cursor until cursor is omitted. Treat cursors as opaque values. total and finished describe the whole run, not the current page. See pagination for the general cursor pattern. This polling flow applies to runs started with /routines/{routine_id}/run. Runs started through the batch API use the separate batch results endpoint.

​
Webhook notifications

The run and run-batch/start requests accept an optional webhook_id. Clay notifies that webhook when the run finishes, so your system can react without polling. Run clay webhooks --help for webhook creation, testing, delivery payloads, and signature verification.

​
Batch run a function routine

For large input sets, create an upload URL, upload JSONL input, then start a batch run.

Batch runs

Learn how batch runs fit into Routines.

​
When to use Workflows

Workflows are also routines, but they are in Alpha and are built differently. Use Workflows when you want to build, edit, validate, run, inspect, or batch-run Clay logic from the plugin or CLI instead of building the logic in the Clay UI.

Workflows (Alpha)

Compare Workflows with functions.