ga4-apis-and-measurement-protocol
Skill1 starsChanged 5 months agoMITView on GitHub
Automate GA4 reporting and configuration and send server-side events with code. Use when the user asks how to pull GA4 data through the Data API v1 (runReport, runPivotReport, runRealtimeReport, batchRunReports, getMetadata, checkCompatibility, funnel or audience exports), manage a property through the Admin API v1 (create key events, custom dimensions, data streams, Measurement Protocol secrets, Google Ads links), send server-side or offline events with the Measurement Protocol, validate events on the debug endpoint, hits a Data API quota or a 25-event Measurement Protocol limit, or asks why UI numbers do not match an API pull.
In this repository129 other files it gives its agents.
- amazon-ads-agentic-and-mcpSkill
- amazon-dsp-account-structureSkill
- amazon-dsp-api-and-automationSkill
- amazon-dsp-audiencesSkill
- amazon-dsp-bidding-and-optimizationSkill
- amazon-dsp-campaign-setupSkill
- amazon-dsp-creative-and-formatsSkill
- amazon-dsp-inventory-and-supplySkill
- amazon-dsp-measurement-and-reportingSkill
- amazon-marketing-cloudSkill
- approval-and-escalation-governanceSkill
- bid-landscape-and-win-rateSkill
- brand-safety-and-suitabilitySkill
- bulk-change-governance-and-rollbackSkill
- change-management-and-incident-responseSkill
- client-deliverable-templatesSkill
- cm360-data-transfer-and-attributionSkill
- cm360-floodlight-and-conversionsSkill
- cm360-reporting-and-trafficking-apiSkill
- cm360-trafficking-and-ad-tagsSkill
- cm360-verification-and-active-viewSkill
- consent-signal-verification-and-decodeSkill
- creative-review-and-approval-queueSkill
- cross-platform-conversion-reconciliationSkill
- cross-platform-launch-qaSkill
- cross-platform-taxonomy-governanceSkill
- ctv-measurement-currenciesSkill
- ctv-supply-and-ad-podsSkill
- curation-and-curated-marketplacesSkill
- curation-and-supply-path-optimizationSkill
- data-quality-and-reconciliationSkill
- data-subject-rights-and-subprocessor-governanceSkill
- direct-response-creative-testingSkill
- discrepancy-and-reconciliationSkill
- dsp-selectionSkill
- dv360-account-setup-and-taxonomySkill
- dv360-advanced-analytics-adhSkill
- dv360-api-and-sdf-automationSkill
- dv360-bid-strategySkill
- dv360-campaign-architectureSkill
- dv360-creative-traffickingSkill
- dv360-custom-biddingSkill
- dv360-deals-and-inventorySkill
- dv360-frequency-and-brand-safetySkill
- dv360-launch-qaSkill
- dv360-measurement-and-attributionSkill
- dv360-pacing-and-optimizationSkill
- dv360-reportingSkill
- dv360-targeting-and-audiencesSkill
- dv360-troubleshootingSkill
- dv360-video-creative-specsSkill
- dv360-youtube-and-videoSkill
- ga4-bigquery-export-and-sqlSkill
- ga4-conversions-and-audiencesSkill
- ga4-events-and-key-eventsSkill
- ga4-explorations-and-reportingSkill
- ga4-property-and-data-stream-setupSkill
- gmp-integration-floodlight-ga4-linkingSkill
- google-ads-account-structureSkill
- google-ads-api-and-bulk-operationsSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 0 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 59
Call getMetadata first when a property has custom dimensions or metrics, because their API names (customEvent:promo_id, …
- Very specific: line 60
Call checkCompatibility for any non-obvious dimension and metric pairing before building the full request, so you catch an incompatible …
- Very specific: line 63
Read the response defensively: check metadata.dataLossFromOtherRow (an (other) row absorbed high-cardinality values) and any sampling …
- Very specific: line 67
Read before you write. properties.get, dataStreams.list, keyEvents.list, customDimensions.list show current state, so a create call does …
- Very specific: line 68
Use the current resource names.
- Very specific: line 69
Create Measurement Protocol secrets under the data stream, not the property: properties/{p}/dataStreams/{s}/measurementProtocolSecrets.
- Very specific: line 176
Read validationMessages in the debug response.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
GA4 APIs and Measurement Protocol
Drive GA4 with code instead of the UI: pull reports at scale through the Data API v1, read and write property configuration through the Admin API v1, and send server-to-server or offline events through the Measurement Protocol. This is the automation layer under GA4. When a task means "do this a thousand times", "on a schedule", "in a pipeline", or "from a server", it lives here.
This skill assumes you know sessions, events, key events, and CPA/ROAS math. For those, see the programmatic-foundations skill. GA4 uses key events, not "conversions", and this skill uses that term throughout.
When to use this skill
- "Pull GA4 data through the Data API." / "runReport / runPivotReport / runRealtimeReport / batchRunReports."
- "List available dimensions and metrics." / "getMetadata / checkCompatibility before I build a report."
- "Build a funnel report or an audience export through the API."
- "Create a key event / custom dimension / data stream / Google Ads link through the Admin API."
- "Generate a Measurement Protocol secret." / "Send a server-side or offline event to GA4."
- "Validate my Measurement Protocol payload." / "Why did my event not show up?"
- "I hit a Data API quota (RESOURCE_EXHAUSTED)." / "How many tokens does a report cost?"
- "Why does my API pull not match the GA4 UI number?"
Boundaries with sibling skills:
- Standing up the property, data streams, retention, reporting identity in the UI:
ga4-property-and-data-stream-setup. - Designing the event model and defining which events are key events (the concept):
ga4-events-and-key-events. - Building audiences and exporting them and key events to ad platforms, plus the June 2026 consent change:
ga4-conversions-and-audiences. - Explore workspace analyses, sampling, and the attribution model in the UI:
ga4-explorations-and-reporting. - The BigQuery export and SQL against the raw nested event schema (a different, unsampled path to the same data):
ga4-bigquery-export-and-sql. - Consent Mode v2 signals and default-vs-update ordering that decide whether events even collect:
gtm-consent-mode-v2. - Reconciling API-derived counts against CM360 and the DSPs:
cross-platform-conversion-reconciliation.
Quick reference
Pick the surface from the job, not from habit.
| Job | Surface | Method or endpoint | Why |
| Read aggregated report data on a schedule | Data API v1 | runReport, batchRunReports | Server-side, quota-metered, unattended |
| Pivot table with column groupings | Data API v1 | runPivotReport | Only method that returns pivots |
| Last 30 minutes of activity | Data API v1 | runRealtimeReport | Realtime is a separate quota category |
| Discover valid dimensions and metrics | Data API v1 | getMetadata | Names change per property (custom dims) |
| Check a dimension and metric combine | Data API v1 | checkCompatibility | Avoids INVALID_ARGUMENT before you run |
| Funnel completion through steps | Data API v1 | runFunnelReport (alpha) | UI-parity funnel from code |
| Snapshot audience membership | Data API v1 | properties.audienceExports (alpha) | Get user list for a saved audience |
| Create a key event or custom dimension | Admin API v1 | properties.keyEvents.create, properties.customDimensions.create | Write config at scale |
| Generate a server-side event secret | Admin API v1 | ...measurementProtocolSecrets.create | Required to authorize MP events |
| Send an offline or server event | Measurement Protocol | POST /mp/collect | Only path for server-to-server hits |
| Test an event before sending live | Measurement Protocol | POST /debug/mp/collect | Production /mp/collect never validates |
Three distinct systems, three auth models:
- Data API and Admin API: OAuth 2.0 or a service account with the Analytics scope. Read (Data API) and read/write (Admin API) property configuration and data.
- Measurement Protocol: an
api_secretbound to a data stream, passed as a query parameter. Write-only event ingestion. No OAuth.
Core process
Reporting through the Data API v1
- Resolve the numeric property ID (the digits, not
G-XXXXXXXXXX). Every Data API call targetsproperties/{propertyId}, so an alphanumeric Measurement ID here fails. - Call
getMetadatafirst when a property has custom dimensions or metrics, because their API names (customEvent:promo_id,customUser:loyalty_tier) are property-specific and you cannot guess them. - Call
checkCompatibilityfor any non-obvious dimension and metric pairing before building the full request, so you catch an incompatible combination as a fast, cheap call instead of a failedrunReport. - Build the request:
dateRanges,dimensions,metrics, and optionaldimensionFilter,metricFilter,orderBys,limit,offset. UsebatchRunReportswhen you need several reports for one property, because batching shares one HTTP round trip and is quota-friendlier than serial calls. - Page through results with
limitandoffsetwhenrowCountexceeds what one response returns (the API caps rows per response). Loop until you have all rows. - Read the response defensively: check
metadata.dataLossFromOtherRow(an(other)row absorbed high-cardinality values) and any sampling metadata before trusting totals. If either flags, the raw truth is in the BigQuery export (ga4-bigquery-export-and-sql).
Configuration through the Admin API v1
- Read before you write.
properties.get,dataStreams.list,keyEvents.list,customDimensions.listshow current state, so a create call does not collide with an existing resource. - Use the current resource names. The
keyEventsresource replacedconversionEvents; write againstkeyEvents. Custom dimensions and metrics are separate resources with hard per-property caps (see Decision rules). - Create Measurement Protocol secrets under the data stream, not the property:
properties/{p}/dataStreams/{s}/measurementProtocolSecrets. The returnedsecretValueis theapi_secretyour event sender uses. - Gate every write. Creating a key event changes what Google Ads can import and bid on; creating a Google Ads link changes data flow. Treat Admin API writes as production changes and confirm with a human before running them.
Server-side events through the Measurement Protocol
- Get two credentials: the stream's Measurement ID (
G-XXXXXXXXXX) for web or thefirebase_app_idfor app, and anapi_secretfrom an Admin API Measurement Protocol secret. - Build the payload: a
client_id(web) orapp_instance_id(app) that matches the on-device gtag/SDK identifier, and aneventsarray where each event has anameand aparamsobject. Adduser_idandconsentwhere you have them. - Validate on the debug endpoint first. POST to
https://www.google-analytics.com/debug/mp/collectand readvalidationMessages. This is the only place GA4 tells you a payload is wrong, because production/mp/collectreturns a 2xx for a broken payload and silently drops it. - Send to production only after the debug response returns an empty
validationMessages. POST tohttps://www.google-analytics.com/mp/collect(orhttps://region1.google-analytics.com/mp/collectfor EU-region collection). - Reconcile in Realtime and DebugView. A correctly sent event appears in
runRealtimeReportand, if you addeddebug_mode, in DebugView. If it never appears, the payload was silently dropped and you missed it in step 3.
Decision rules and thresholds
Data API quotas (get these right before you build a pipeline)
Quotas are per property and split into three independent categories: Core, Realtime, and Funnel. A runReport charges Core; a runRealtimeReport charges Realtime. Standard vs 360 limits:
| Quota | Standard | 360 |
| Tokens per property per day | 200,000 | 2,000,000 |
| Tokens per property per hour | 40,000 | 400,000 |
| Tokens per project per property per hour | 14,000 | 140,000 |
| Concurrent requests per property | 10 | 50 |
| Server errors per project per property per hour | 10 | 50 |
Token cost per request is not fixed. It scales with date range, number of dimensions, filter complexity, and data cardinality, so a 90-day, high-cardinality report can cost many multiples of a 1-day summary. Read propertyQuota in every response to see remaining tokens and back off before you hit RESOURCE_EXHAUSTED. Daily quotas reset at midnight Pacific. Rule of thumb: widen date ranges and reduce request count with batchRunReports rather than firing many small serial reports, and cache metadata rather than calling getMetadata on every run.
Measurement Protocol hard limits
| Limit | Value |
| Events per request | 25 |
| Parameters per event | 25 |
| User properties per request | 25 |
| Event name length | 40 characters |
| Parameter name length | 40 characters |
| Parameter value length | 100 (Standard), 500 (360) |
| User property name length | 24 characters |
| User property value length | 36 characters |
| POST body size | Under 130 kB |
Backdating window (timestamp_micros) | 72 hours |
timestamp_micros is Unix epoch in microseconds, not milliseconds. An event older than 72 hours is dropped. Event names must start with a letter and use only letters, numbers, and underscores, and the prefixes firebase_, ga_, and google_ are reserved. Reserved event and parameter names (session_start, first_visit, user_engagement, and others) are rejected. The full reserved list and the field map are in references/measurement-protocol-limits.md.
Admin API configuration caps
Per-property caps are enforced by the API, so plan the taxonomy before you create resources: event-scoped and user-scoped custom dimensions and custom metrics each have a fixed maximum, and key events have their own cap. Hitting a cap returns an error on create, not a silent truncation. Design the dimension set once (in ga4-events-and-key-events) rather than creating dimensions ad hoc through the API and running out.
When API totals will not match the UI
- Sampling: high-complexity Explore queries sample; most Data API core reports do not, so an API number can legitimately exceed a sampled UI number.
(other)row: when a dimension exceeds its cardinality limit, low-frequency values collapse into(other). CheckdataLossFromOtherRowin the response.- Attribution and identity: the API respects the property's reporting identity and attribution model, so a mismatch often traces to a different identity space, not a bug.
- Freshness: the Data API can lag the UI by hours for the current day. Compare closed days, not today.
- For byte-exact, unsampled truth, leave the reporting APIs and query the BigQuery export (
ga4-bigquery-export-and-sql).
Consent and legal posture
The Measurement Protocol lets a server send events GA4 would otherwise never see, which makes consent your responsibility, not the browser's. Set the consent object (ad_user_data, ad_personalization) on MP payloads and only send events for users whose consent you have recorded. Consent Mode v2 requires ad_storage, analytics_storage, ad_user_data, and ad_personalization, and a June 2026 change gates ads-data flow on consent, so a server bypass that ignores consent is both a data-quality and a legal problem. For the consent framework and signal wiring, see gtm-consent-mode-v2 and privacy-and-consent.
Reference material
references/data-api-methods-and-quotas.md: every Data API v1 method with its request and response shape, the dimension/metric filter grammar, pagination andbatchRunReportspatterns, the full quota table with token-cost drivers, and the common error codes (INVALID_ARGUMENT,PERMISSION_DENIED,RESOURCE_EXHAUSTED). Read this when building or debugging a report pull.references/admin-api-resources.md: the Admin API v1 resource tree, the create/list/patch/delete method map per resource, thekeyEvents-replaced-conversionEventschange, required fields for key events, custom dimensions and metrics, data streams, Measurement Protocol secrets, and Google Ads links, plus the per-property caps. Read this when reading or writing property configuration.references/measurement-protocol-limits.md: the exact endpoint URLs, required query params and body fields for web vs app, the full limits table, the reserved event and parameter names and prefixes, theconsentobject fields, the debug-endpointvalidationMessagescodes, and a worked payload. Read this when building or validating a server-side event sender.
Templates and examples
Data API runReport request body (sessions and key events by channel, last 28 days):
{
"dateRanges": [{ "startDate": "28daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "sessionDefaultChannelGroup" }],
"metrics": [{ "name": "sessions" }, { "name": "keyEvents" }],
"orderBys": [{ "metric": { "metricName": "sessions" }, "desc": true }],
"limit": 100
}Admin API create a key event (mark generate_lead as a key event):
POST https://analyticsadmin.googleapis.com/v1beta/properties/123456789/keyEvents
{ "eventName": "generate_lead", "countingMethod": "ONCE_PER_EVENT" }Measurement Protocol offline purchase event (validate first, then send):
POST https://www.google-analytics.com/debug/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_SECRET
{
"client_id": "1993.1735689600",
"timestamp_micros": 1751414400000000,
"consent": { "ad_user_data": "GRANTED", "ad_personalization": "DENIED" },
"events": [{
"name": "purchase",
"params": {
"transaction_id": "T-10492",
"currency": "USD",
"value": 129.00,
"items": [{ "item_id": "SKU-88", "item_name": "Trail Shoe", "price": 129.00, "quantity": 1 }]
}
}]
}Read validationMessages in the debug response. Empty array means the payload is valid; then repost to /mp/collect (no /debug) to record it.
Common pitfalls
- Using the Measurement ID as the property ID. Data API calls need the numeric property ID (
123456789);G-XXXXXXXXXXis the stream Measurement ID for the Measurement Protocol. Swapping them is the most common first failure. - Trusting
/mp/collectbecause it returned 200. Production never validates and returns 2xx for garbage. Validate on/debug/mp/collectand only trust an emptyvalidationMessages. - Backdating past 72 hours. Offline events with a
timestamp_microsolder than three days are dropped with no error. Send within the window or accept the loss. - Silent quota exhaustion. Firing many small serial
runReportcalls burns hourly tokens fast. Batch reports, cachegetMetadata, readpropertyQuota, and back off beforeRESOURCE_EXHAUSTED. - Writing to
conversionEvents. That resource is replaced; write key events against thekeyEventsresource or the call fails or targets a deprecated path. - Sending MP events without consent signals. A server can push events the browser suppressed, which breaks Consent Mode and creates legal exposure. Set the
consentobject and only send for consented users. - Comparing today's API pull to the UI. The Data API lags for the current day. Reconcile on closed days, and for exact figures use the BigQuery export.
- Guessing custom dimension API names.
customEvent:andcustomUser:names are property-specific. Pull them fromgetMetadata, do not hardcode from memory.
Sources
- Analytics Data API v1 overview (as of July 2026)
- Data API v1 quotas (as of July 2026)
- Analytics Admin API v1 overview (as of July 2026)
- Measurement Protocol for GA4 overview (as of July 2026)
- Sending Measurement Protocol events (as of July 2026)
- Measurement Protocol reference and limitations (as of July 2026)
- Validating Measurement Protocol events (as of July 2026)
- BigQuery export schema (as of July 2026)
- About key events (as of July 2026)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

