Clay (API): what this connector can do

Member·5 minutes to read

What this page is for

docs/connectors/clay-api.md is the setup guide for whoever runs your organisation's Botseon deployment. This page is the other half: what Clay actually lets a bot do once it is connected to your Clay workspace, what it asks you for along the way, its limits, and how to take the connection away again, in Botseon and at Clay.

Check your Clay credits, run one of your Clay functions on records after you approve it, and read its results.

The catalogue has two Clay entries. Clay is Clay's own hosted MCP server, which you sign in to. Clay (API) — this page — is Botseon's own connector to Clay's public API, which you connect with a key.

Connecting it

In Clay, open API and CLI in the left sidebar (under Orchestration), select the API keys tab and press Add API key. Give it a name, pick its scopes, and copy the key — Clay shows it only once. This is a workspace key: the personal key on your Clay profile page does not work here.
In Botseon, open Plugins, find Clay (API) and press Add.
Under Accounts, paste the key and tick what the bot may do: clay-api:read (the balance and a run's results) and, if you want the bot to run functions, clay-api:run. Then press Connect. Botseon asks Clay for your workspace's credit balance with the key — a read that uses no credits — and keeps the key only if Clay accepts it.

If Clay refuses the key, nothing is saved and you are asked to check it. Clay also refuses a correct key when your workspace has not been enabled for its public API yet; making a new key does not fix that — ask Clay support to enable the public API for your workspace.

Before a bot can run a function, tick API & CLI in that function's Integrations settings in Clay, and give the bot its Routine ID (it looks like function:t_…).

What a bot can do with it

Read — Clay tells a bot things, nothing changes

Tool	What it does
`clay-api.get_credit_balance`	Read the workspace’s remaining Clay credits and actions.
`clay-api.get_function_run`	Read a Clay function run’s progress and, once it is complete, its results.

Write and spend — adds records to your function and uses your Clay credits

Tool	What it does
`clay-api.run_function`	Run one of the workspace’s Clay functions on up to 100 input records.

The permissions it asks for, in plain words

Every call a bot makes through this connector is tagged with what kind of thing it is. Only the tags below ever apply here.

read — Looks something up. Nothing changes, and nothing is sent anywhere. A bot never has to ask first for this.
write — Changes something: a run adds its records to the function's own table in Clay. A bot asks you first.
spend — Uses something you pay for: a function run uses your workspace's Clay credits. A bot always asks you first, every time, and no saved rule can answer for you.

Limits

One function run takes at most 100 records. Larger batches are not available through this connector.
A run finishes in the background. The bot reads its progress with clay-api.get_function_run until it is complete.
Clay allows 300 requests a minute per workspace; above that the bot is told to wait.
It cannot read or write your Clay tables, or search Clay's people and company data. Clay's public API has no endpoint that writes rows, and its table and search endpoints need extra plans or access Clay grants per workspace.

Disconnecting

In Botseon

Open Plugins from the sidebar, press this connector's card to open its detail page, and under Accounts press Remove next to the account — or Uninstall to remove the plugin and every account connected to it at once. Either one deletes the stored key immediately: nothing more is read or run through it from that moment on. Install a plugin walks through the same screen step by step.

At Clay

Removing the account in Botseon deletes the stored key from Botseon, but the key itself stays valid at Clay until you delete it. Do that in Clay under API and CLI → API keys — the same place you created it — which is the only way to be sure nothing else can use it, since Botseon has no way to revoke a key it did not issue.

What Botseon keeps, and how your data is used

Whatever a bot reads or sends through this connector becomes part of your conversations and the record of that run — the same records, and the same retention schedule, as everything else a bot works on. Botseon is the processor for that content; your organisation decides what it may read and remember, and can delete it sooner than the schedule would on its own.

Your data is sent to a model provider only to produce the bot's answer, and for nothing else — it is not used to train any model. The Privacy Policy's Models and How long we keep it sections have the full detail, including exactly how long each kind of record is kept for.