Clay API in 2026: Public API, Webhooks and HTTP API Explained

Facts checked October 16, 2026. Every Clay fact here comes from Clay's developer docs, Clay University, its pricing page and its changelog, read on October 16, 2026. Where Clay's own pages disagree, we say so.

Does Clay have an API?

Yes, and "the Clay API" can mean four different things:

One trap in the search results: the GitHub repository called "clay-mcp" now redirects to Mesh, formerly the "Clay" personal CRM at clay.earth. That is a different company from Clay at clay.com.

What can the Clay Public API do?

The Public API focuses on running work and reading data. Its OpenAPI spec lists 13 paths:

• Run routines: start an asynchronous run of a Clay-managed function, a custom function you built in Clay, or a Workflow, for 1 to 100 items per call, then poll for the result. Larger jobs upload a JSONL batch.
• Search: run people and company searches in query mode and page through results.
• Read tables: query table rows. The tables endpoint is read-only.
• Credits: GET /credits/balance returns your balance, and reading it costs nothing.
• Workflow runs: query runs of Workflows, still labeled alpha or beta in Clay's docs.
• Outbound webhooks: Clay can POST to your URL when a run finishes, signed with an X-Clay-Signature HMAC-SHA256 header. Clay's docs say delivery is not guaranteed, so poll as a fallback.

A custom function only appears in the API once you toggle its API access on in Clay.

How do I get a Clay API key?

Create one in Clay under API and CLI > API keys, or run clay api-keys create in the CLI. Send it on every request in the clay-api-key header. Keys are tied to a Clay user and that user's workspace access, so a key can do whatever its owner can. The CLI itself signs in through the browser with clay login, or clay login --device on a headless machine. Some older integrations, such as Zapier, still use Clay's legacy key.

Which Clay plans include the API?

Clay University says the developer platform, meaning the API, CLI and Agent Plugin, is available on every Clay plan, including Free and trials. What changes by plan is how many search results the API can return, per Clay's developer docs:

Going over returns HTTP 402. Clay University gives the same caps per year rather than per 30 days, so confirm the period with Clay if you plan near the ceiling. Two more plan rules: structured table queries (joins, ranges and paging past 100 rows) need Enterprise table sync, and Clay's pricing page lists "Clay API access" among Enterprise extras, which reads as that table sync rather than the Public API.

How much does the Clay API cost?

Clay says there is no added cost for building or running through the API or CLI: a run spends the same Actions and Data Credits it would in the app. Since March 2026 Clay prices in two units:

• Actions measure platform work, from under $0.01 each. Every enrichment step, AI prompt and HTTP API call is one Action; webhook imports use none.
• Data Credits buy data and AI from Clay's marketplace, from $0.05 each. Clay says a fully enriched record typically costs 6 to 20 Data Credits.
• Misses are not charged: Clay's pricing FAQ says an enrichment that returns nothing costs no Data Credits or Actions.

Our Clay pricing guide covers the plans in depth, and the Clay waterfall cost breakdown works through what one row costs.

What are the Clay API rate limits?

Clay enforces a per-workspace request limit but does not publish the number. Over it, the API returns 429 with a Retry-After header, and responses may carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Plan around the limits Clay does publish:

• Rows: 200 per table on Free, 50,000 per table on Launch and Growth; bulk enrichment past 50,000 records is Enterprise. Workflows, still in alpha, avoid the table cap.
• Webhook sources: up to 50,000 submissions per source.
• Runs: 1 to 100 items per routine call; use a JSONL batch for more.

How do Clay webhooks and the HTTP API column work?

These are the two older ways teams wire Clay to other systems, and both need Growth or Enterprise (Clay's 14-day trial includes them):

• Webhook source (into Clay): POST JSON to a table's webhook URL, with an optional auth token, and each payload becomes a row. Webhook imports cost no Action, and a source accepts up to 50,000 submissions.
• HTTP API column (out of Clay): a column that calls any API with GET, POST, PUT or DELETE, with stored header accounts and a rate limit you set per column. Each call is one Action. As a source it can page through up to 50,000 rows.

The HTTP API column is how most teams add an outside enrichment step to a Clay table; our guide to using the Cleanlist API in Clay shows one end to end.

Is Clay MCP the same as the Clay API?

No. Clay MCP is a hosted server at api.clay.com/v3/mcp, signed in with OAuth, that lets AI tools call Clay; Clay made it generally available as "MCP for Reps" on July 14, 2026. Official connectors cover Claude, ChatGPT, Claude Code, Codex, Microsoft 365 Copilot and Glean. People and company search through MCP is free, enrichment costs what it does in Clay, and a first connection comes with 500 credits. Our Clay MCP server review covers it in depth.

What can't the Clay API do?

• Write tables. The tables endpoint is read-only; send rows in through a webhook source.
• Show its rate limit. The per-workspace number is not published.
• Budget per key. Clay says credit budgets are not available on the developer platform yet, though Workflow budgets shipped on October 5, 2026.
• Guarantee webhook delivery. Clay says run-finished webhooks are not guaranteed.
• Run Workflows as a stable surface. Workflows are still alpha or beta in Clay's docs.

When does a waterfall enrichment API fit better?

Cleanlist AI publishes this page, so treat this section as a disclosed vendor entry. Clay's API runs the workflow you build in Clay, including any waterfall you assemble and order yourself. Cleanlist AI's enrichment API is one endpoint with the waterfall built in: each lookup runs through 25+ data providers and every work email is verified before it comes back.

Pick Clay's API if your team already builds in Clay and wants to trigger those tables and functions from code. If you are weighing a move off Clay altogether, our Clay alternatives guide sorts ten tools by the job they replace. Pick Cleanlist AI's if the job is verified emails and phone numbers without building the waterfall, or call it from a Clay HTTP API column and keep both. The data enrichment API explainer covers how this kind of API works, and plans are on the pricing page.

Frequently asked questions

Does Clay have a public API?

Yes. Clay's Public API launched on July 9, 2026 and became generally available on September 15, 2026. It lives at api.clay.com/public/v0 and authenticates with a clay-api-key header.

Is the Clay API free?

Access is: Clay says the developer platform is on every plan, including Free. Runs still spend Actions and Data Credits at the in-app rates, and the Free plan caps API search at 100 results per 30 days.

Can I add rows to a Clay table through the API?

Not through the Public API, whose tables endpoint is read-only. Send rows to a table's webhook source instead, which needs the Growth or Enterprise plan and accepts up to 50,000 submissions per source.

What is the difference between Clay webhooks and the Clay API?

A webhook source moves data into a Clay table from another app. The Public API lets your code run Clay's functions and searches and read results. The HTTP API column goes the other way, calling outside APIs from inside a table.

What is the Clay API rate limit?

Clay applies a per-workspace limit and does not publish the number. When you exceed it, the API returns 429 with a Retry-After header telling you how long to wait.