API scopes
Every scope on the Convultra API and MCP server, the consent sentence a user approves, what it covers and which operations it unlocks.
On this page · 6 sections
The Convultra API and MCP server are in Beta. A key or OAuth grant is given exactly what an integration needs and nothing more. Scopes narrow access; they never widen it. A key with conversions:read can still only see the projects its owner can see, and no scope grants sight of a project the owner has no claim on.
The scopes
Each scope shows the sentence a user is asked to approve, on the consent screen and beside the checkbox in the Developer tab, and what it covers.
| Scope | Consent sentence | Covers |
|---|---|---|
projects:read | See which projects you have and whether tracking is healthy | List projects, tracking health and integration status. Never credentials. |
analytics:read | Read traffic and revenue analytics | Overview, timeseries, breakdowns, events, funnels, AI referrals, filtered-out traffic and Search Console. |
conversions:read | Read conversions, values and attribution | Conversion list and detail, including ad click ids and session id, so you can reconcile against the ad platforms. |
delivery:read | Read conversion delivery status to ad platforms | The server-side forwarding log and its summary. |
delivery:write | Retry failed deliveries | Re-queue a failed conversion delivery. Implies delivery:read. |
spend:read | Read ad spend and return | Ad spend, ROAS, CPA and campaign detail from connected ad platforms. |
audiences:read | Read audience definitions and sizes | Audience rules, status and member counts. Never the members themselves. |
annotations:read | Read notes on your charts | Chart annotations explaining movement. |
annotations:write | Add notes to your charts | Create, edit and delete chart annotations, for example from a deploy pipeline. Implies annotations:read. |
exports:write | Request data exports | Queue an asynchronous raw data export and read its status. |
Which scope unlocks what
| Scope | Operations |
|---|---|
| (none required) | get_me, get_metric_definitions |
projects:read | list_projects, get_project, get_tracking_health |
analytics:read | get_overview, get_timeseries, get_breakdown, list_events, get_event_timeseries, get_funnel, get_ai_referrals, get_filtered_out |
conversions:read | list_conversions, get_conversion, get_attribution, get_recovery |
delivery:read | list_deliveries, get_delivery_summary |
delivery:write | retry_delivery |
spend:read | get_spend |
audiences:read, annotations:read, annotations:write, exports:write | No operations yet. The scopes exist, can be granted and appear in discovery, but nothing in this version reads or writes through them. Granting them changes nothing today. |
spend:read adds fields elsewhere
spend:read also adds fields to operations you reach with another scope. With it, get_overview returns spend, blended_roas and cpa; get_timeseries returns a spend metric; and get_breakdown returns spend, roas and cpa on the source, channel and utm_campaign dimensions. Without it those fields are absent or null, and the response says why in spend_omitted_reason. That is a missing scope, not missing data.
Missing spend:read does not produce insufficient_scope on those three operations. They succeed and explain the absent spend fields.
Write scopes imply read
Granting delivery:write grants delivery:read, and annotations:write grants annotations:read.
What a Claude connector asks for
A connector added through Claude’s custom connector flow requests the six read scopes an assistant needs: projects:read, analytics:read, conversions:read, delivery:read, spend:read and annotations:read. It asks separately, later, for anything beyond them. See Connect Claude.
Stepping up
When a credential lacks a scope, the API returns 403 insufficient_scope. details.required_scopes names every scope the operation needs, not only the missing one, and the WWW-Authenticate header repeats them, so an OAuth client can step up in one round trip. For an sk_ key, create a new key with the scope; scopes on an existing key are fixed at creation. See API errors.