Permissions and limits
Scopes, workspace and brand requirements, paid access, rate limits, idempotency and the quota implications of measurement runs.
Scopes
| Scope | Allows |
|---|---|
read | The four read tools and the underlying GET endpoints. |
write | Also add_prompt, trigger_run and, with workspace authorisation, create_project. |
A credential is bound at creation to a workspace, a list of brands, or both, and cannot be edited afterwards. Creating a
write credential for specific brands requires member-level access to them; a read credential requires viewer access.
Creating one for a workspace requires owning the workspace.
| Operation | Additional requirement |
|---|---|
create_project | A write credential authorised for a workspace (a brand-only credential gets workspace_scope_required). |
add_prompt | Admin access to the brand. |
trigger_run | Admin access to the brand and active paid access. |
Brands the credential cannot see return not found, never "forbidden", so ids are not disclosed.
What is re-checked on every request
The API does not trust the tool list the server registered at startup. On every call it checks that the credential is not revoked, the per-key rate limit, the operation's scope, the owner's paid access, and current brand membership. Revoking a key, losing a membership or lapsing a subscription therefore takes effect immediately.
Rate limits
Each credential has its own request limit (60 requests per 60 seconds by default). Beyond it the API answers 429 with a
Retry-After header, and the server reports "Rate limit exceeded for this API key; retry after about N seconds". Separately,
manual measurement runs have a daily quota per plan; see below.
Quota and provider calls
- Reads (
list_*,get_visibility_summary,get_run_status) spend nothing. create_projectandadd_promptcount against the plan's project and prompt limits, not run quota.trigger_runconsumes one daily manual-run allowance per dispatch and makes paid provider calls (questions × providers). Retrying with the same idempotency key does not consume more.- Measurement runs also happen on a schedule for active questions, independently of MCP. Prompts created through MCP are
pausedunless you ask foractive.
Plan limits and allowances depend on your plan; check the dashboard rather than assuming a number.
Paid access
If the credential owner has no active paid access, every call fails with "no active paid access" (HTTP 402). The same applies to previously working credentials if a subscription lapses.
Idempotency and retries
Reads are safe to repeat. Writes are idempotent by key; see Write tools. Do not rely on retries as exactly-once for provider execution: a timed-out provider call may still have been processed.