Query and deliver your marketing data

Send Authorization: Bearer <API_KEY>. Keys begin with gma_live_ or gma_test_. Never put them in URLs, browser code or a shared spreadsheet. Test keys return labeled synthetic data and cannot deliver to Google destinations. The dashboard uses your existing sign-in.

A 202 response includes the extraction id and Location header. Reusing an Idempotency-Key with the same query returns the same extraction; changing the query returns 409. Keys are scoped to the originating credential. Poll GET /v1/exports/{id}; do not treat 202 as completed delivery. States are queued, running, succeeded, failed, blocked and cancelled.

• Daily reports require a date dimension. Read the source catalog before selecting dimensions and metrics; not every source supports every level or field combination.
• Every live result identifies its source, account, currency and timezone when available. Missing metadata is null and relevant warnings accompany the result. Currency is never silently converted.
• Conversions retain their platform definitions. Reach, frequency and ratios should not be summed across days. Meta and Google CTR are percentages; Search Console CTR is its native fraction.
• Results expose schema_version, columns, rows, metadata and a next_cursor. Cursors belong to one immutable extraction.
• The API refuses a source response that it detects as truncated. Daily limits currently include TikTok below 1,000 rows, Google Ads below 10,000, GA4 up to 10,000 and Search Console below 10,000. Select fewer dimensions or use smaller accounts if a daily segment is too large. Provider reporting and privacy limits still apply.
• CSV text that could execute as a spreadsheet formula is escaped. Google Sheets values are written with RAW input semantics.

1. 01Ask your MCP assistant for a Google Sheets export. Specify source, accounts, metrics, dimensions and any filters. get_sheet_export_options lists supported fields; prepare_sheet_export saves a draft.
2. 02Review the small export app in the conversation: choose fixed dates, the last complete days, or a start date through yesterday; choose a new spreadsheet or select an existing file with Google Picker. Google uses the limited drive.file permission.
3. 03Choose once, daily or weekly. Recurring refreshes use the selected timezone and local time, including daylight-saving changes. Missing required settings must be completed before starting. Existing tab values require explicit replacement permission.
4. 04Start the reviewed revision. A backend job extracts the data and publishes the complete report to the selected tab. Later runs replace that same tab; keep formulas in other tabs. The conversation can be closed.
5. 05Dashboard → Data → Exports lists saved exports, execution history, last/next refresh, pause/resume, manual refresh and archive. Edit report settings by reopening the export in your conversation. Saving edits pauses refreshes until you start the revised export.

The same tools work as text when the MCP client does not support Apps. Google authorization and file selection open a short first-party handoff page; reload the export afterwards. MCP configures the export, while the shared Data backend executes jobs without an LLM. Exports use a scoped identity tied to the administrator who starts them; account removal, lost membership and revoked Google access block subsequent work. API keys are not needed for this flow.

filters combine conditions with AND. filter_groups combines groups with OR, and every condition inside a group uses AND. Conditions apply to individual daily rows. Text contains/not_contains matching ignores case; equality and membership comparisons are exact. Filter fields must be included in the selected columns. Cross-date totals and cross-source joins are not supported by these exports.

The community connector reads the latest complete snapshot of a synchronization. Create a dedicated key with syncs:read and exports:read, the report's selected accounts, and its destination grant. Configure the synchronization in Looker Studio. Its date controls filter the snapshot; change the saved report or schedule lookback to extract a wider period. The connector refuses reports above 20,000 rows instead of silently truncating them. Larger reports should use the native BigQuery connector.

The direct connector uses a Google Apps Script deployment. Its source and deployment instructions are in connectors/looker-studio in the repository. API credentials are held in Google Apps Script user properties and are not included in report URLs. Looker Studio's data credential settings determine who can view a shared report; review them before sharing. Monetary values preserve their account currency: filter or group by currency before combining spend.

Owners and admins can select account grants, permissions, allowed destination IDs, expiry, exact IP allowlists, requests per minute, rows per month and concurrent jobs for each key. A key cannot exceed the workspace plan. Keys are stored as hashes and shown in full only at creation. Suspension is reversible; revocation is permanent. Rotation creates a replacement and expires the previous key after an overlap period.

Removing an account from the workspace immediately removes it from existing keys. Access is checked again before source reads and delivery steps. Revocation stops subsequent work; requests already accepted by a destination cannot be recalled. Schedules created using an API key stop when that key is disabled or expires; rotation transfers schedules and pending jobs to the replacement without resetting usage. After a suspension, resume schedules explicitly.

A key can read exports made by its own logical identity and exports delivered to its explicitly granted destinations, subject to its current account grants. The initial Data allowance is included in the existing plan and blocks work at its limit, with no automatic overage charges. Requests are counted for public API operations; status polling and authenticated downloads do not consume request credits. Rows are counted once per successfully checkpointed segment. Retries do not charge the same segment twice. Results expire according to the current plan; download them or deliver them to your own storage. Google services have their own usage costs and quotas.