Clay's API, Explained: What You Can (and Can't) Do Outside the Spreadsheet

Yes, Clay has an API now. Not the old in-table HTTP column, not the MCP server living inside your chat client. A real developer API and CLI, shipped July 9, 2026 at developers.clay.com, open to every plan Clay sells, new and legacy both.

If you searched "does Clay have an API" and landed on a guide telling you no, that guide predates the launch or missed it entirely. A Medium post from April 2025, written well before the launch, still flatly claims Clay "does not offer a public API." More striking: a Crustdata blog post, published July 21, 2026, twelve days after Clay's own launch, argues Clay's lack of a public REST API is "an architectural limitation that goes deeper than a missing feature." Crustdata sells a competing data API. Worth keeping in mind when you read their framing. This piece corrects the record, then goes further: what the API lets you build, where the three "Clay plus your code" surfaces stop overlapping, and whether calling Clay from code changes what you pay.

It doesn't. There's one new lever worth knowing about, though.

The confusion is real. Three different "Clay plus your code" features.

Search "Clay API" and you'll find three separate features tangled into one answer, sometimes in the same paragraph of the same blog post. They shipped years apart. They do different jobs. Only one of them is what people actually mean when they ask, in 2026, whether Clay has an API.

The old in-table HTTP API column

This is the one most Clay users already knew about. Add an HTTP API column to a table, point it at a GET, POST, PUT, or DELETE endpoint, and the table calls out to an external service as one more enrichment step, then writes the response back into the row. It's been in Clay for years. It is not what launched on July 9. A secondary source, a Medium analysis of Clay's March 2026 pricing restructure, claims this specific feature now sits behind the $495/mo Growth plan (that Medium piece's own figure, and worth noting Growth's current list price has since moved; check clay.com/pricing for what it costs today). I couldn't confirm the gating claim itself against Clay's own current docs. Treat it as likely, not settled.

Clay's MCP server

Clay in Claude, Clay in ChatGPT, Clay in Codex, whatever the chat client calls it. This is Clay's MCP server: a way to ask a chat tool to run a Clay search or enrichment conversationally, without opening a spreadsheet at all. Clay rolled pieces of this out between January and June 2026. It's useful. It's also not the API this piece is about. MCP is tool-calling inside a conversation. It isn't a general-purpose way to call Clay from code you own and control.

The new developer API and CLI

This is the one. developers.clay.com, launched July 9, 2026, is the first time Clay has offered true headless access: call Clay from your own backend, a cron job, or an autonomous agent, with no UI interaction at all. Clay's own announcement put it plainly: "You can now build directly from your terminal. Run the Agent Plugin in Claude Code, Codex, or Cursor to search Clay data, run Functions, and create, edit, and trigger Workflows." And it isn't locked behind a tier. Available for everyone, on new and legacy plans, per the same announcement.

What launched on July 9, 2026

Strip away the Agent Plugin for a second and look at what actually shipped. A public API. A CLI you install and run from a terminal. Documentation at developers.clay.com covering three primitives (more on those below) plus authentication, webhooks, and rate limiting.

The Agent Plugin is a separate, adjacent thing, and Clay is upfront that it isn't finished. It's explicitly open beta, and as of this writing it only runs on Mac and Linux. Setup happens through github.com/clay-run/agent-plugins: run clay login, get the clay CLI on your PATH, then point Claude Code, Codex, or Cursor at it. Once it's wired in, the agent picks whichever primitive fits the task on its own.

The worked example straight from Clay's own repo: "Find 20 Series B fintech companies in NYC, then get each CEO's work email." One instruction, and the agent chains a Search call into a Routines call without you writing either request by hand. That's the part worth sitting with. Clay didn't just add an endpoint. It gave an agent the ability to use Clay the way a developer would, start to finish, from a coding session instead of a browser tab.

The three core primitives: Search, Routines, Tables

Search

Search does what it sounds like. Structured filters over companies and people, the same targeting logic you'd build inside a Clay table, now callable directly. Create a search from your filters, list which filter fields are available for a given source type, then page through results with a search iterator. No spreadsheet required to originate the query.

Routines

Routines run Clay-managed functions, your own custom functions, or full Workflows, triggered from outside the UI. Here's the part that trips people up: execution is asynchronous. You submit 1 to 100 items in a single call, then hit a separate endpoint to check progress or pull results, or set up a webhook and let Clay tell you when it's done. Need more than 100 items? There's a batch path: get a presigned upload URL, drop a JSONL file of inputs on it, and start an async batch run over the whole file.

1. Submit up to 100 items per call (or a JSONL batch via presigned URL)
2. Poll run status, or wait for the completion webhook
3. Fetch results once the run reports complete

If you've built against a synchronous REST API before, budget time to unlearn that instinct. Submit, then poll or wait. It's not a blocking call, and treating it like one is the most common mistake in a first integration.

Tables

Tables let you run a structured query across one or more tables, closer to querying a database than filling a spreadsheet. And it's explicitly Enterprise-only, both in Clay's API overview and in community questions the launch announcement didn't fully answer. Search and Routines are yours on Launch or Growth. Tables is not. Not yet, anyway.

Does the API change what gates your cost? No.

Here's the question none of the competing guides answer, and it's the one a technical reader actually has. Does calling Clay from code change what you're billed for?

No. Clay's own mechanism doc settles it. HTTP API calls appear right there under what consumes Actions, and the doc goes further: "Using your own API keys (still counts as platform usage)." An API call is billed the same as the identical action taken by clicking around inside the UI. There is no separate, cheaper API tier of consumption.

Two meters, and it's worth being precise about both. Actions get consumed by any enrichment from any provider, AI usage, GTM execution steps like sending an email or syncing a CRM, HTTP API calls, and data warehouse exports. Data Credits get consumed specifically by enrichments sourced from Clay's own marketplace, priced per data type per provider, generally in the 0.5 to 10-plus credit range.

The two meters don't behave the same way when you run low, either. Actions don't roll over, and there's no way to buy more outside a plan upgrade. That's the hard ceiling. Data Credits do roll over (up to double your monthly allotment on monthly plans), and you can buy one-time top-ups at roughly a 30% premium, per Clay's own doc. So a Routine triggered from the CLI that calls a marketplace enrichment provider draws both: one Action for the orchestration step itself, plus Data Credits for the underlying data purchase, at the same per-provider rate it costs inside the app. Calling it from code doesn't discount either meter.

The one new lever: BYOK headless routing

There is one real architectural choice the API surfaces, and most in-app Clay users never face it. Bring your own key. Route a Routine through your own provider API key instead of Clay's marketplace connection, and it still costs 1 Action per call, but draws zero Data Credits. The provider bills you directly instead.

BYOK isn't new. It existed inside the Clay UI already, mostly untouched. What's new is that it's now the obvious default for anyone building headless or agent-driven waterfalls, instead of a setting most people never open. If Actions are your hard ceiling and Data Credits are the elastic, purchasable meter, BYOK is how you convert a chunk of Data Credit spend into a direct provider relationship you control. It doesn't touch your Actions budget at all. Every orchestration step, keyed or not, still burns one.

What you still can't (or shouldn't) do

A few honest limits, stated plainly instead of buried in a footnote.

Tables querying is Enterprise-only. On Launch or Growth, Search and Routines are your two primitives. Full stop.

Exact rate limits for the new API aren't publicly documented as of this writing. Clay indexes a rate-limits guide page, but it returned a 404 when I tried to fetch it directly. Numbers circulating on community forums reference legacy plan names from before the March 2026 restructure and describe the older HTTP API surface, not this one. I'm not citing them here, because I can't confirm they're current.

API key scoping is thin too. Key-based auth exists. Whether you can scope a key to read-only, or restrict it to a single primitive, isn't documented anywhere I could find.

And the Agent Plugin is open beta, Mac and Linux only. Not yet.

Last one, and it matters more than it sounds like it should: this is asynchronous by design. If your team needs a synchronous request-response call, the API will not feel like a drop-in replacement for one.

How to get started

Getting a first call running takes four steps, not forty. Install the CLI. Run clay login to authenticate. Point Claude Code, Codex, or Cursor at the Agent Plugin via github.com/clay-run/agent-plugins if you want an agent driving instead of writing raw requests by hand. Then make your first Search or Routines call and see what comes back.

# one-time setup
clay login

# then, agent-driven (Claude Code / Codex / Cursor with the Agent Plugin installed)
# "Find 20 Series B fintech companies in NYC, then get each CEO's work email"

Don't try to memorize the full API reference before you start. developers.clay.com is the canonical source, and it changes faster than any article summarizing it will stay accurate, including this one. Use this piece to understand the shape of the thing. Use their docs for the actual parameter names.