Keys and credits

A credit pays for a call. This page tells you what costs a credit, what costs nothing, where your credits come from and where to follow your usage.

What costs a credit

Every billed call costs one credit: a read such as GET /students, or an operation called with POST /operations/<name>. The credit is debited before the call runs. The API and MCP draw on the same credits.

A call that fails can still cost a credit. A 400 or a 404 is billed when the call got as far as your data:

• a refused parameter on a list, such as limit=500 (400 VALIDATION);
• an ID that cannot be found or is not yours (404 NOT_FOUND);
• an operation that ran, then refuses the request itself (400 VALIDATION).

A request the API refuses before running it costs nothing: an unknown operation name (404 OPERATION_NOT_EXPOSED), a missing scope (403), a dry_run on an operation that has no preview (400 DRY_RUN_UNSUPPORTED), or an invalid body. On an operation, an argument that its schema refuses, such as a missing field or a wrong type, is refunded (400 VALIDATION). The refusal of the operation itself stays billed.

What is free or refunded

• GET /me, GET /openapi.json, GET /operations and GET /events. You can read GET /openapi.json and GET /operations even without a key.
• A preview with dry_run: true, for an operation that can do one.
• A replay with the same Idempotency-Key (Idempotency-Replayed: true).
• The errors 409 (IDEMPOTENCY_MISMATCH, CONFLICT), 401, 402, 403 and 429.
• A 5xx response on a read, and a read interrupted before the end.

Where your credits come from

1. Included credits. Your plan gives you a number of them each month: you see it in the app. They are used first. At the reset, they go back to the level of your plan, and the ones you did not use are not added to the next month. The date is in credits.plan_resets_at, in the X-Credits-Plan-Resets-At header and in the app.
2. The reserve. These are the credits bought in packs or granted. They never expire, and they are used only once your included credits are spent. Only the team owner buys packs.

When nothing is left, billed calls get a 402 CREDITS_EXHAUSTED, which costs nothing. They resume at the reset, or as soon as a pack is added.

Where to follow your usage

In the app, open Settings › Integrations › API keys:

• the Keys tab shows, above the list, the credits you have left, the calls of the month, the reset date and your reserve;
• the Credits & packs tab details the movements, such as the monthly allowance, purchases and refunds, and offers the packs;
• the Call log tab lists the calls that reach the credit step (billed, refunded, previews and replays) with their key, their operation, their status and their credit. GET /me and the refusals that fall before it, such as a 401, a 403 or a 429, leave no row.

Through the API, GET /me gives your balance for free, and X-Credits-Remaining follows you on every billed call.

Spend less

• Ask for limit=200 on lists: a page costs one credit, whatever its number of objects.
• Reread only the changes with since, instead of rereading everything.
• Keep the same Idempotency-Key for every retry of one write: the replay is free.
• Create one key per tool: the log then shows which one consumes.

The script in Write a script applies these rules. To read the credit headers on a real call, go back to First call.