How to Wire Clay's API Into a Claude Code Agent (A Working Waterfall, Not a Demo)

Clay's developer API and CLI went live on July 9, 2026. As of this writing that's fifteen days old, and the content trying to explain it is either pre-launch or working around a stranger's unofficial wrapper. So here's the actual build: install Clay's own Agent Plugin, structure a waterfall as a Routine instead of a table, and handle the async contract that governs every call, whether it's coming from an agent, a cron job, or your own backend. You'll leave with a running agent-triggered waterfall and the general API pattern underneath it. Nothing here is a demo dressed up as a tutorial.

What "wiring Clay into an agent" actually means

Three separate things get lumped together as "Clay's API," and only one of them is what launched this month.

The first is the old in-table HTTP API column, a feature that lets a Clay table call out to an external endpoint as an enrichment step. That's been around for a while and it's not this. The second is Clay's MCP server, which lets you talk to Clay conversationally inside ChatGPT, Claude, or Codex. Also not this, and also not new. What launched July 9 is the third thing: a public developer API at developers.clay.com, paired with a CLI and an Agent Plugin that let Claude Code, Cursor, or Codex search Clay data, run functions, and trigger workflows straight from your terminal, no UI required.

One more thing worth knowing before you start typing commands. Tables querying through the API is Enterprise-only. Search and Routines, the two primitives this build actually uses, are available on every plan including Free.

This also covers headless, not just Claude Code

Quick scope note before Step 1. Everything from here forward, the async contract, the batch path, the Actions math, describes the general API any backend uses to call Clay without a UI. A cron job hitting the same endpoints on a schedule runs into the exact same submit-then-poll pattern an agent does. The Claude Code agent is the worked example carrying this piece. It is not the only thing this applies to. If you're building a plain server-side integration and skipping the agent part entirely, keep reading anyway. Step 4 is written for you too.

What you need before you start

A Clay account, first. API access isn't plan-gated. Clay's own launch announcement says it's "available for everyone, on new and legacy plans." You'll also need a Clay API key and Claude Code installed. Check the agent-plugins repo's setup docs for any version requirements before installing.

One real constraint: the Agent Plugin is explicitly open beta, and per Clay's own agent-plugin page it's "available on Mac and Linux during open beta." If you're on Windows, this exact walkthrough isn't for you yet.

Step 1: install and authenticate the plugin

Clay's own setup path runs through Claude Code's plugin marketplace mechanism.

# add Clay's plugin marketplace, then install the plugin itself
/plugin marketplace add clay-run/agent-plugins
/plugin install clay@clay-plugins

# authenticate against your Clay workspace
clay login

One more thing worth checking before you assume the order doesn't matter. This is the Agent Plugin, not Clay's separate MCP server, and it's explicitly open beta, so auth-timing behavior between clay login and an already-running agent isn't something this research could confirm either way. Check Clay's Agent Plugin README for any auth-timing gotchas around clay login and restarting the agent before you build a habit around one order or the other.

Step 2: let the agent pick the right primitive

Clay's own setup skill hands the agent a decision tree, and it's worth understanding before you start prompting.

A waterfall, structurally, is a Routine. Not a table. That distinction matters more than it sounds like it should, because every piece of existing Clay content either avoids the word "Routine" entirely or quietly conflates it with the old table-based UI workflow. This build uses Routines throughout. If your agent's first instinct is to open a table and start adding columns, redirect it. That's the old workflow, not the API one.

Step 3: build the waterfall as a Routine

This is the part that actually earns the "not a demo" claim in the title, so it gets the most space.

Why a Routine, not a table, for agent-driven work

A table is a UI object. You click into cells, you watch rows populate, a human is implicitly in the loop. A Routine is closer to a function: it takes a batch of items, runs a defined sequence of steps against each one, and returns results through the API, no UI rendering required at any point. For agent-driven or backend-driven work, that's the right shape. The agent never needs to see a spreadsheet to run one.

Structuring provider order inside the Routine

The tradeoff logic here is the same one that governs any waterfall, in Clay's UI or out of it. Cheapest, narrowest providers go first. Broadest, most expensive providers sit at the back as the catch-all for whatever the cheap ones couldn't find. Order isn't a fixed leaderboard; it's workload-dependent, and it should shift based on what your specific list looks like. Inside a Routine, that ordering becomes configuration rather than table-column setup:

// Illustrative shape only. Field names and structure are not
// confirmed against a public Clay schema; verify against
// developers.clay.com before shipping this as-is.
{
  "routine": "email-enrichment-waterfall",
  "steps": [
    { "provider": "clay-native-email", "run_if": "email is empty" },
    { "provider": "fullenrich",        "run_if": "email is empty" },
    { "provider": "byok:hunter",       "run_if": "email is empty" }
  ]
}

Translating "run only if empty" into an API-driven gate

Here's the mechanic that's missing from every existing piece of Clay content I found while researching this. In the UI, "run this provider only if the previous one came up empty" is a checkbox. Through the API, it has to be something you build explicitly, because a Routine call returns a run reference, not an inline result. You check whether the prior step's output is empty, then decide whether to fire the next provider in the sequence. Skip that gate and you're paying for every provider on every row, whether the first one already found the answer or not. That single detail is probably the most expensive mistake available in this whole build.

Step 4: the async contract, submit then poll or get a webhook

This is the section that applies to any caller, agent or not, so read it that way.

Why Clay's execution model has always been asynchronous

Clay's API executes a routine against 1 to 100 items per call. It does not hand you a result in that same response. What comes back first is a run reference:

# illustrative request shape; confirm the exact endpoint path
# and payload against developers.clay.com before use
curl -X POST https://api.clay.com/routines/{routine_id}/execute \
  -H "Authorization: Bearer $CLAY_API_KEY" \
  -d '{"items": [ ... ]}'

# response is a reference, not a result
# { "run_id": "run_8f2a91", "status": "queued" }

Then you either poll a status endpoint or wait on a signed webhook callback. There's no blocking call anywhere in this model. If you build assuming a synchronous request/response, your first real test run will sit there timing out and you'll assume something's broken. Nothing's broken. It just hasn't finished yet.

Polling vs. webhook callbacks

Polling is the simpler thing to build first, and it's fine for early testing. You hit a status endpoint every few seconds until the run reports done. Webhooks are the more efficient path at any real volume, since you're not burning cycles asking "done yet?" in a loop. Clay's docs describe webhook signature verification as part of the delivery model, and you should actually use it rather than trusting an unsigned payload. I'd start with polling to get the logic right, then graduate to webhooks once the agent loop is running in something closer to production.

Step 5: run it at volume with the batch path

A single Routine call caps at 100 items. Past that, there's a separate batch path: request a presigned upload URL, PUT a JSONL file of your inputs to that URL, then start an async batch run over it. Results come back the same way as a single run, polling or webhook, just at scale. And this is exactly what a cron job or an internal service would do too. No agent required for any of it. The batch path is the general on-ramp for volume; the agent is just one way to trigger it.

Step 6: budget for the real cost ceiling

Every API call, including the agent's own test runs while it's iterating on a workflow, burns an Action. Clay's own mechanism doc lists "HTTP API calls" directly under what consumes Actions, right alongside "Using your own API keys (still counts as platform usage)." That second line matters more than it looks like it should.

Actions don't roll over, and you can't top them up on their own. The only lever is a plan upgrade. Data Credits work differently: they roll over (up to double the monthly limit on monthly plans), and you can buy more as a one-time top-up at a premium, per Clay's own docs.

The one new lever: BYOK headless routing

Bring your own key for a given provider and the call still costs 1 Action, same as any other. But it skips Data Credits entirely, because the provider bills you directly instead of routing through Clay's marketplace. BYOK existed inside the UI before this API shipped. What's new is that programmatic building makes it the natural default rather than a checkbox almost nobody touches.

Clay's pricing at the time of writing (verify again before you build a budget around it, since these numbers have already moved once this year) runs Free at 500 Actions and 100 Data Credits a month, Launch starting around $167/mo with 15,000 Actions, and Growth listed at $446/mo month-to-month with 40,000 Actions. A secondary source claims the older in-table HTTP API feature specifically requires Growth. Clay's own current docs don't confirm that for me, so treat it as likely, not settled. What Clay's launch announcement does say plainly: the new developer API itself isn't plan-gated at all.

Step 7: verify before the agent trusts the result

One more step, easy to skip when you're excited the pipeline is finally running end to end. Before the agent hands a waterfall's output downstream, treat verification as its own real step, not an afterthought. Valid-looking syntax and an actually-deliverable result are two different things, and an autonomous agent has no instinct to tell them apart on its own. A bad result a human would've caught by eyeballing a table is a much smaller problem than the same bad result silently accepted and acted on by an agent three steps further down the chain.

Common mistakes that burn Actions fast

The mistakes here aren't exotic. Treating the API as synchronous and either polling too aggressively or not building for async at all is the most common one, and it usually shows up as a confused "why is this hanging" message on the first real test. Letting an agent's exploratory calls run unmetered during development is the second, and it's the one that quietly eats a month's Action budget before the production waterfall has even shipped. Skipping the run-if-empty gate from Step 3 means double-firing every provider on every row regardless of whether the first one already found what you needed, which is expensive in the most boring possible way. And defaulting to Data-Credit-heavy marketplace providers when a BYOK route would've converted that same call into a direct, usually cheaper, provider bill is the one people don't notice until they look at a bill three weeks in.

Where this differs from what's already out there

Most existing "Clay plus code" content either predates this API entirely, describing a pricing structure and a feature set from before March 2026 as if it were current, or routes through unofficial third-party tooling that has to be adopted and maintained on top of Clay's own supported path instead of using it directly. This piece uses Clay's official install path end to end: the actual plugin, the actual primitives, the actual cost model. Nothing here requires you to trust a stranger's webhook proxy or a third-party CLI wrapper. That's not a knock on the people who built those things before Clay shipped its own path. It's just not necessary anymore.