---
ref: tool:clay/run-routine
name: Run a routine
company: company:clay
workflows: [workflow:high-intent-visitors, workflow:champion-job-change-loop]
access: [cli, api]
tags: [capability:enrich-contacts, category:data-provider, has:api, has:cli]
docs: https://developers.clay.com/api-reference/routines/execute-a-routine-against-1-100-items
updated: 2026-09-27
---

# Run a routine

Runs a Clay-managed function such as Work Email or Company Domain, or a team's own function, on 1 to 100 records and returns a run id to poll for results.

Clay-managed functions cover work email, phone, job title, company domain,
employee count, tech stack, funding and job openings. List routines to find
the id and input schema before running: the managed Work Email routine needs
a full name, company name and company domain. Poll
`GET /routines/run/{routine_run_id}/results` until the run is complete.

## Set up

Use the first option your agent supports.

### CLI (official)

Install the command, then confirm it runs.

```sh
npm install --global @clay-run/cli
clay --version
```

Run `clay routines runs start`.

### API (official)

- Base URL: https://api.clay.com/public/v0
- Endpoint: `POST /routines/{routine_id}/run`
- Auth: send the header `clay-api-key: $CLAY_PUBLIC_API_KEY`
- Get a key: https://app.clay.com/workspaces/~/settings/account?accountTab=api-keys-beta
- Docs: https://developers.clay.com/public-api/authentication

Before doing anything else, make one read-only call to confirm access.

## Rules

- Ask the user before anything that sends messages, costs money, or changes data.
- Never print API keys.