Limits
| Limit | Value |
|---|---|
| Reads | 120 a minute per token |
| Writes | 20 a minute per token |
| Requests per IP address | 120 a minute |
| Setup-code exchanges per IP address | 60 a minute |
| Activations | 25 per campaign per hour |
| Contract uploads | 10 per campaign per hour |
| Campaigns created | 20 per workspace per day |
| Page size | 1 to 100 |
| Response size | About 60,000 characters. Larger pages return fewer items and a nextCursor |
| Request body | 64 KB. 4.4 MB for a tool that takes a file |
Over a limit: 429 with Retry-After in seconds, or a refused result with retryAfterSeconds. MCP requests are sent one at a time; a batch is a 400.
Errors
json
{ "error": { "code": "not_found", "message": "No such campaign." } }| Status | Code | Fix |
|---|---|---|
| 400 | invalid_request | Check the parameter named in the message. Do not build cursors yourself |
| 400 | invalid_setup_code | The setup code was used, expired, or mistyped. Press the tile on the Agents page for a new one |
| 401 | missing_token, invalid_token | Send Authorization: Bearer <token>, or sign in again |
| 401 | token_revoked, token_expired, token_orphaned | Create a new token on the Agents page, or connect the app again |
| 403 | insufficient_scope | Create a token with the scope the message names |
| 403 | wrong_principal | This token is not allowed to call that tool |
| 404 | not_found | The id is not in your workspace. Another workspace's campaign, a missing one, and a malformed id all look the same |
| 409 | idempotency_conflict | Use a new key |
| 429 | rate_limited | Wait for Retry-After |
| 503 | agent_api_unavailable | Retry with backoff |
Over MCP, an error is a tool result with isError: true and the same code and message.
Good practice
- One token per agent, with the fewest scopes it needs. An agent that only reads needs no action scope.
- Keep tokens in a secret store. Never in a browser, a mobile app, a prompt, a URL, or a repository.
- Give acting tokens an expiry. Use Never only for read-only tokens you watch.
- Look at Activity on the Agents page to see what your agents did.
- Revoke on doubt. It takes one click and works at once.
- Tool results are kept by the AI product you use. That is why creators' contact details never appear in them, and your team's email addresses appear only to a token given
team:manage. Activity names the address when an agent gives someone access, so you can spot one nobody meant. Only your workspace's members can open it, and they can already see your team.
Versioning
/v1 only changes by adding: new tools, new optional parameters, new fields. Nothing is renamed or removed inside /v1. Tool names are stable. The OpenAPI document is generated from the running server, so it is always current.
Help
Email founders@scoutnow.me with the error code, the time, and the tool you called. Never send a token.