{"id":17204,"date":"2026-10-10T07:20:00","date_gmt":"2026-10-10T05:20:00","guid":{"rendered":"https:\/\/www.lukaswojcik.com\/blog\/?p=17204"},"modified":"2026-10-09T22:41:29","modified_gmt":"2026-10-09T20:41:29","slug":"ga4-measurement-protocol-payloads-every-field-every-limit","status":"publish","type":"post","link":"https:\/\/www.lukaswojcik.com\/blog\/en\/digital-analytics\/ga4-measurement-protocol-payloads-every-field-every-limit\/","title":{"rendered":"GA4 Measurement Protocol Payloads: Every Field, Every Limit, and Why the Endpoint Answers 204 to Broken JSON"},"content":{"rendered":"

A Measurement Protocol request is one HTTPS POST: a query string carrying two credentials, and a JSON body carrying the events. It is the way data reaches a GA4 property from a server rather than from a browser \u2014 offline conversions from a CRM, a payment confirmed by a webhook, an app backend, a bot-free replay of hits that an ad blocker swallowed.<\/p>\n

It is also the only ingestion path in the whole stack that never says whether it worked.<\/p>\n

\n\"The
What a payload is made of, and what the production endpoint answers when parts of it are wrong.<\/figcaption><\/figure>\n

What the endpoint answers<\/h2>\n

Nine requests went to https:\/\/www.google-analytics.com\/mp\/collect<\/code> on 9 September 2026, all with a made-up measurement ID so that nothing could be recorded anywhere. Seven of them were deliberately broken.<\/p>\n

Eight of the nine came back 204 No Content<\/strong> in about 100 milliseconds with an empty body. Not only the valid one: also the event whose name started with an underscore, the empty events<\/code> array, the payload with an invented top-level field, the request with no client_id<\/code>, and a body that was not JSON at all. A request sent with no query string whatsoever<\/strong> \u2014 no measurement ID, no API secret \u2014 also returned 204.<\/p>\n

Exactly two things produced an HTTP error, and neither is a verdict on the payload. A body of 140 kB was refused with 413<\/strong> and an HTML error page from the front end, because it exceeded the documented 130 kB cap before any parsing happened. A GET<\/code> was refused with 405<\/strong>.<\/p>\n

The European endpoint region1.google-analytics.com<\/code> behaves identically. Over five runs each, the median round trip from the same server was 90 milliseconds to both hosts.<\/p>\n

The response code therefore tells you only that the request arrived. It does not tell you whether the event was understood or stored, or whether a parameter was dropped. Those problems remain invisible when sending; they appear only as missing data in a report hours later.<\/p>\n

Where the payload actually goes<\/h2>\n

Two parts, and they are easy to confuse.<\/p>\n

The query string<\/strong> carries the credentials: measurement_id<\/code> for a web stream (or firebase_app_id<\/code> for an app stream) and api_secret<\/code>, which is created per stream in the GA4 admin. Neither belongs in the JSON. Placed there they become unknown fields, and an unknown field is not ignored \u2014 it makes the entire payload unreadable.<\/p>\n

The body<\/strong> is a JSON object with a fixed set of permitted keys:<\/p>\n

{\n  \"client_id\": \"1234567890.1700000000\",\n  \"user_id\": \"crm-88213\",\n  \"timestamp_micros\": 1788000000000000,\n  \"consent\": { \"ad_user_data\": \"GRANTED\", \"ad_personalization\": \"DENIED\" },\n  \"user_properties\": { \"customer_tier\": { \"value\": \"gold\" } },\n  \"events\": [\n    {\n      \"name\": \"purchase\",\n      \"params\": {\n        \"transaction_id\": \"T-8891\",\n        \"currency\": \"EUR\",\n        \"value\": 20,\n        \"session_id\": \"1700000000\",\n        \"engagement_time_msec\": 100,\n        \"items\": [\n          { \"item_id\": \"A-1\", \"item_name\": \"Shirt\", \"price\": 10, \"quantity\": 2 }\n        ]\n      }\n    }\n  ]\n}<\/code><\/pre>\n
Besides these, the reference permits user_data<\/code>, user_location<\/code>, ip_override<\/code>, device<\/code>, user_agent<\/code>, non_personalized_ads<\/code> and validation_behavior<\/code>. That is the complete list. Anything else \u2014 a stray event<\/code> key copied from a dataLayer object, an ecommerce<\/code> wrapper, a note to a colleague \u2014 costs the whole request.<\/p>\n
The identity fields<\/h2>\n
client_id<\/code> is required on a web stream, and it is the single field that decides whether an event joins an existing user or invents a new one. The recommended form is two positive numbers joined by a period, which is what gtag('get')<\/code> hands out and what the built-in Analytics Client ID variable returns in Google Tag Manager. The full _ga<\/code> cookie value, GA1.1.1234567890.1700000000<\/code>, is accepted as well; the two numbers are the part inside it.<\/p>\n
A value invented on the server is accepted too, and that is the expensive mistake. A fresh identifier per request produces a fresh user and a fresh session every time \u2014 a property that looks busy and consists entirely of one-event sessions with a 100 % engagement-free rate.<\/p>\n
App streams use app_instance_id<\/code> instead: 32 hexadecimal characters from the Firebase SDK, not a client ID under another name. Sending both does no harm and no good; the field belonging to the other stream type is ignored.<\/p>\n
user_id<\/code> is optional, up to 256 characters, and must be a string. It is a join key, not a person: an email address or a phone number in that field is personal data, which the Google Analytics terms forbid and which is grounds for deleting a property. The same applies to every event parameter and every user property.<\/p>\n
The two parameters that decide whether the reports add up<\/h2>\n
An event without session_id<\/code> belongs to no session. It is still stored and still countable, but sessions, engaged sessions and the session-scoped dimensions do not add up, and the event may be missing from Realtime entirely.<\/p>\n
An event without engagement_time_msec<\/code> contributes nothing to average engagement time, which then reads as zero for the traffic that arrived this way.<\/p>\n
Neither is required, neither produces a warning anywhere, and both are the usual answer to “the events arrive but the report is wrong”. session_id<\/code> must be a positive integer \u2014 a timestamp in the ordinary case \u2014 and may be sent as a number or as a string of digits. Letters in it are refused.<\/p>\n
The event and its name<\/h2>\n
An event is an object with exactly two permitted keys, name<\/code> and params<\/code>. A timestamp put beside them as a third key breaks the payload; the per-event timestamp goes inside params<\/code> as timestamp_micros<\/code>.<\/p>\n
Names must start with a letter and may contain only letters, digits and underscores. Hyphens, dots and spaces are refused outright. Names are case sensitive<\/strong>, which is the quiet one: Purchase<\/code> is accepted, is stored, and is a different event from purchase<\/code> \u2014 it will never reach the e-commerce reports, because those are wired to the lowercase name.<\/p>\n
Thirty-one names are reserved for Google’s own use, among them session_start<\/code>, first_visit<\/code>, user_engagement<\/code>, app_remove<\/code> and error<\/code>. Three further names \u2014 screen_view<\/code>, ad_impression<\/code> and in_app_purchase<\/code> \u2014 exist but are permitted on app streams only. On a web stream they are simply not collected, and nothing anywhere says so.<\/p>\n
Parameters, and the limits that apply to them<\/h2>\n
Every limit in the protocol, in one place:<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
What<\/th>\nLimit<\/th>\n<\/tr>\n
JSON body<\/td>\nunder 130 kB<\/td>\n<\/tr>\n
Events per request<\/td>\n25<\/td>\n<\/tr>\n
Event name<\/td>\n40 characters<\/td>\n<\/tr>\n
Parameters per event<\/td>\n25<\/td>\n<\/tr>\n
Parameter name<\/td>\n40 characters<\/td>\n<\/tr>\n
Parameter value<\/td>\n100 characters, 500 on an Analytics 360 property<\/td>\n<\/tr>\n
User properties per request<\/td>\n25<\/td>\n<\/tr>\n
User property name<\/td>\n24 characters<\/td>\n<\/tr>\n
User property value<\/td>\n36 characters<\/td>\n<\/tr>\n
user_id<\/code><\/td>\n256 characters<\/td>\n<\/tr>\n
Items per event<\/td>\n200<\/td>\n<\/tr>\n
Custom parameters per item<\/td>\n10<\/td>\n<\/tr>\n
Backdating<\/td>\n72 hours<\/td>\n<\/tr>\n<\/table>\n
Parameter names may not begin with _<\/code>, firebase_<\/code>, ga_<\/code>, google_<\/code> or gtag.<\/code>, and firebase_conversion<\/code> is reserved outright. User property names carry the same prefix rules plus five reserved names, of which user_id<\/code> is the one people reach for by accident \u2014 the user ID belongs at the top level, not in user_properties<\/code>.<\/p>\n
Only items<\/code> may hold an array. Every other parameter takes a single value; a nested object handed to one is dropped, and the report shows the parameter as absent rather than as wrong.<\/p>\n
Where the two maxima collide<\/h2>\n
Twenty-five events per request and two hundred items per event are both documented, and they cannot both be used. Measured on generated payloads with realistic item fields \u2014 ID, name, brand, category, variant, price, quantity:<\/p>\n