Guide 198 · Conversions · GA4 + Tag Manager

Mark a key event with the Admin API: one POST, the counting method, and the default value

Checked 11 November 2026 · Verification: figures recomputed in Python with decimal arithmetic; downloadable JSON carries the same recomputed figures · Steps traced to Analytics Help, opened 11 November 2026 · 7-minute read

The Admin API marks a key event with one POST to the property's keyEvents collection — eventName, a required counting method, and an optional default value and currency.

Expected signal

After step 5, the response holds the new key event's resource name and creation time, and the event appears in Admin under Events as a key event.

Download the reference: the Admin API key event request (JSON) (1488 bytes, MD5 7682aaab8b14d6ce204d00abae1db86e). It holds the report or event definition and the worked example with the recomputed figures shown on this page.

What you need

The property resource name: properties/ followed by the property ID — for example properties/123456789.
An OAuth token with the analytics.edit scope. Creating a key event requires https://www.googleapis.com/auth/analytics.edit; a read-only token is refused.
The event name, already collected. The key event refers to an event the property already receives — eventName is immutable once the key event exists, so pick the name before you send the call.

The trace

Build the request body. The body is a KeyEvent object. eventName is the event to mark — for example generate_lead. countingMethod is required: ONCE_PER_EVENT counts each event instance as a key event, and ONCE_PER_SESSION counts an event instance as a key event at most once per session per user. Pick the method when you create the key event; the worked example below counts the same session under both.
Add a default value when the event arrives without one. The optional defaultValue object holds numericValue and currencyCode, both required when the object is present. The default value populates the value parameter for every occurrence of the key event where that parameter is unset, and the currency applies where no currency is set. The currency code must be in ISO 4217 format, for example CAD. The worked example below prices four valueless occurrences at $25.00 each.
Send the POST. POST to https://analyticsadmin.googleapis.com/v1beta/properties/123456789/keyEvents — the property ID in the path is your property's ID, not the example's. The body holds the KeyEvent object. Send it with the analytics.edit scope.
Read the response for what it is. A successful response holds the newly created KeyEvent: name in the form properties/{property}/keyEvents/{keyEvent}, eventName, createTime as an RFC 3339 timestamp, deletable, and custom. custom is true when the key event refers to a custom event and false when it refers to a default event — custom events count towards the maximum number of custom key events per property.
Check the result in the interface. The key event appears in Admin under Events. The record you hold in the API response is the same record the interface shows: the same event name, the same counting method, the same default value. If the interface does not show it, the resource name in the response tells you which property the call actually hit.

Dead ends

DEAD END — LEAVING OUT THE COUNTING METHOD. The counting method is required. A body with an event name and no counting method is not a valid create request. Decide once per event or once per session before you send the call, not after the response comes back.

DEAD END — USING THE OLD CONVERSION EVENTS METHOD. The conversionEvents create method is deprecated: use CreateKeyEvent instead. A call to the old method is a call to a method Google has replaced, and the keyEvents collection is where new key events are created.

DEAD END — MARKING A DEFAULT EVENT AND EXPECTING A FREE SLOT. Custom events count towards the maximum number of custom key events per property; default events do not count the same way. The custom flag in the response tells you which side of that line the new key event falls on — read it before you count your remaining slots.

End state

The Admin API is the programmatic path to the same star the interface shows in Admin under Events. It suits a rollout across properties: one POST per key event, each with its own counting method and default value. The worked example below counts one session under both methods and prices the default value.

Worked example — stated inputs, recomputed results. A property marks generate_lead as a key event with a default value of $25.00 in Canadian dollars. The counting and the attribution below are recomputed from the documented rules.

Figure	Value
Default value per occurrence	$25.00 CAD
Occurrences with no value set	4
Value attributed by the default	$100.00 CAD
`generate_lead` events in one session	3
Counted with ONCE_PER_EVENT	3
Counted with ONCE_PER_SESSION	1

$25.00 × 4 = $100.00. With ONCE_PER_EVENT, each of the 3 events in the session counts; with ONCE_PER_SESSION, the same 3 events count as 1 key event.

Sources

Google Analytics — Method: properties.keyEvents.create — the POST endpoint, the required parent path parameter, the KeyEvent request body, and the analytics.edit scope
Google Analytics — REST Resource: properties.keyEvents — the KeyEvent fields — eventName is immutable, countingMethod is required, defaultValue is optional — the two counting methods, the default value rule, and that custom events count towards the per-property limit

Checked 11 November 2026. The click paths above are the ones in Google's help and developer pages, opened in full on 11 November 2026. No step in this guide was run inside a live Analytics property, because that needs a Google sign-in and this site does not sign in as anyone. The worked-example figures on this page were recomputed in Python with decimal arithmetic, and the downloadable JSON file carries the same recomputed figures. Google moves menu items without warning; if a path on this page no longer matches, the linked help page is the current map.