Letting an AI agent run matching jobs without handing it your credits
What an agent needs from a matching API: expiring tokens, hard call limits, a price before every run, and a way to stop. What we built, and what we have not.
A person clicks “Run” once. An agent can call the same endpoint a thousand times before anyone looks at the screen. Every run in Match Data Studio costs credits, so the first question about letting an agent use the API was not how to let it in. It was how to keep one confused loop from spending an account’s balance overnight.
This post is what we built to answer that, and where it still falls short.
What an agent can do today
The API is plain REST: HTTPS, JSON bodies, a bearer token. Humans writing scripts and agents calling tools use the same surface, which is the point. An agent needs no special protocol to talk to it.
The base address is https://api.match-data.studio/v1. Every response is either {"success": true, "data": ...} or {"success": false, "error": "..."}. These are the calls most workflows start with:
| Call | Path | What it does |
|---|---|---|
| POST | /projects | Create a project |
| POST | /projects/{id}/files | Upload a CSV (multipart form) |
| PUT | /projects/{id}/canvas-graph | Save the pipeline as JSON |
| POST | /projects/{id}/canvas-estimate | Price a run without starting it |
| POST | /projects/{id}/canvas-run | Start a sample or a full run (spends credits) |
| GET | /runs/{id} | Status and progress |
| POST | /runs/{id}/stop | Stop a running run |
| GET | /runs/{id}/download | A link to the results file, valid for 15 minutes |
| GET | /credits | Balance and history |
A typical session is: create a project, upload the files, save a pipeline, price it, run a sample, look at the output, then run the full job and fetch the file. Nothing in that list needs a person, which is exactly why the next part matters.
What stands between an agent and your balance
None of these is clever. Each one closes a specific way an unattended caller can go wrong.
| Guardrail | What it does | What it does not do |
|---|---|---|
| Tokens expire | You choose 30, 90, 180 days or a year when you create one. A token is shown once and stored only as a hash. At most 5 valid tokens per account. | It does not narrow what the token can do while it is valid. |
| Some actions need a person | A token cannot create or revoke tokens, buy credits, or manage your team. Those require a signed-in session. | It can still start runs and delete projects. |
| Call limits | 120 requests per minute for each token and 10,000 calls per month for the account, only for token calls. Over a limit: 429 with Retry-After. | It limits the number of calls, not their cost. One full run is one call. |
| A price before every run | canvas-estimate returns the most a run can use (and, when an earlier run of the same pipeline exists, what we expect it to use), and charges nothing. A sample run reads the first 50 rows of each file by default. | An agent can skip the estimate. Nothing forces the order. |
| Credits are the ceiling | A run is paid from the balance, so it cannot spend more than the account holds. A failed run is refunded in full. | Whatever the balance holds can be spent. |
| Stop | POST /runs/{id}/stop ends a run. The credits that finished steps used are kept, and the rest are returned. | A step already in progress runs to its end, but you are not charged for it. |
The honest reading of that table is the last column. The biggest gap today is that a token has the same reach as its owner, apart from the person-only actions. The server already understands narrower permissions, but the app does not offer them yet, so we are not claiming them. Until it does, the practical protection is the combination of a short-lived token and a small balance.
The limits, in detail
The limits are counted in shared storage, not in each server’s memory. The reason is how the API is served: requests can land on many servers at once, and a counter that lives in one server’s memory only counts the calls that server saw. A limit that works for one server and not for ten is not a limit.
Two behaviors are worth knowing before you write a client:
- A call refused for the minute does not count toward the month. An agent that hits the per-minute limit and backs off does not burn its monthly allowance on the refusals. Calls with a bad token or without permission for the action are not counted at all.
- We fail open. If the counter storage is unavailable, the call goes through. We chose availability over strictness: an outage on our side should not stop a customer’s job, and the credit balance remains the hard ceiling either way.
There is one known imprecision. The minute limit uses fixed one-minute windows, so a client can send up to twice the limit in a short burst that straddles two windows. For protecting an account from a runaway loop that is acceptable. For billing it would not be, which is why the limits count calls and the balance counts money.
Every response to a token call shows where you stand:
X-RateLimit-Limit-Minute: 120
X-RateLimit-Remaining-Minute: 117
X-RateLimit-Limit-Month: 10000
X-RateLimit-Remaining-Month: 9412
When a limit is hit, the answer looks like this, with a Retry-After header in seconds:
{
"success": false,
"code": "RATE_LIMITED",
"error": "Rate limit exceeded: 120 requests per minute for each token. Try again in 23 seconds."
}
The monthly version has the code MONTHLY_LIMIT and tells you the date the count starts again.
What a well-behaved agent does
Price first, run a sample, and respect the limits. This is the pattern we would put in an agent’s instructions:
import time
import requests
BASE = "https://api.match-data.studio/v1"
HEADERS = {"Authorization": "Bearer mds_..."}
project_id = "..." # from POST /projects
def call(method, path, **kwargs):
while True:
r = requests.request(method, BASE + path, headers=HEADERS, timeout=60, **kwargs)
if r.status_code != 429:
return r
body = r.json()
if body.get("code") == "MONTHLY_LIMIT":
raise RuntimeError(body["error"]) # waiting will not help; tell a person
time.sleep(int(r.headers.get("Retry-After", "5")))
estimate = call("POST", f"/projects/{project_id}/canvas-estimate", json={"type": "full"}).json()
# stop here and ask a person if estimate["data"]["max"] is more than you are willing to spend
The two details that matter are in the comments. A per-minute refusal is worth waiting out. A monthly refusal is not, and the right response is to stop and tell someone.
For the account itself, we suggest three things whenever an agent is involved: a token that expires in weeks, not a year; a balance of what the job needs, not what the account could hold; and a sample run before any full run.
Teaching an agent the API
A guardrail only helps if the agent follows it, and an agent only follows what it has read. So we publish three things, and none of them needs a token to read:
- An OpenAPI description at
https://api.match-data.studio/v1/openapi.json. Every call, its parameters, the scope a token needs for it, and the error answers. Client generators and agent frameworks can read it directly. - A step catalog at
https://api.match-data.studio/v1/canvas/node-catalog. Every step a pipeline can use, with its ports, its settings, an example of each, and whether it costs credits, plus three complete example pipelines. Add?format=mdfor a compact text version. This is what lets an agent build a pipeline instead of being handed one. - An agent skill at
https://api.match-data.studio/v1/skill. ASKILL.mdfile that teaches the workflow and the rules in this post: price before every run, sample first, ask a person before a full run, back off on a 429. It does not copy the step list; it tells the agent to read the live catalog, so a skill you installed last month does not go stale.
To install the skill for a coding agent:
mkdir -p .claude/skills/match-data-studio
curl -s https://api.match-data.studio/v1/skill -o .claude/skills/match-data-studio/SKILL.md
We keep these from drifting with tests, not with discipline. A route a token can call but the description does not mention fails our test suite. So does a step in the editor that is missing from the catalog, and an example pipeline that our own validator rejects.
What we have not built
We would rather list this than imply it:
- Narrower tokens in the app, for example read-only. The server supports the idea; the app does not offer it. Until it does, the protection is a short-lived token and a small balance.
- Enforced ordering. Nothing forces an agent to price a run before starting it. The skill asks for it, and the balance limits the damage, but the API will start a run you did not price.
Keep reading
Ready to match your data?
Create a free account, upload your CSV files, and configure matching in plain English. 100 free credits — no credit card required.
Free account No credit card Match your files in minutes