Toolcog home
Search ⌘ + K

Command Palette

Search for a command to run...

Sign In

Google Analytics Admin organizes resources around Accounts and Properties. Accounts own Properties; Properties own most measurement configuration (data streams, custom dimensions/metrics, conversion events, links to Firebase/Google Ads, measurement protocol secrets). Many operations require full resource names like accounts/123 or properties/123 (not just a numeric ID). Understand how those names flow through requests—most create/list calls take a parent that is a full resource name, and most get/patch/delete calls take a name that is a full resource name.

Key entities and how they relate

  • Accounts (accounts/{account}): top-level containers. Accounts contain Properties. Use account-level operations when you want account-wide information (change history, account summaries, or account-level access reports).
  • Properties (properties/{property}): measurement containers where configuration lives. DataStreams, CustomDimensions, CustomMetrics, ConversionEvents, FirebaseLinks, GoogleAdsLinks, KeyEvents, and MeasurementProtocolSecrets are children of a Property.
  • DataStreams (properties/{property}/dataStreams/{dataStream}): represent web/app streams. Measurement protocol secrets attach to specific data streams.
  • CustomDimensions / CustomMetrics (properties/{property}/customDimensions, properties/{property}/customMetrics): created and managed at the property level. CustomMetrics can be archived via an archive operation rather than deleted.
  • Links (Firebase/Google Ads): created under a Property (properties/{property}/firebaseLinks, properties/{property}/googleAdsLinks). Firebase links can be listed and deleted by their full name.
  • Account summaries: provide a compact view of accounts and the properties they contain; they are the fastest way to discover property resource names and their display names.
  • Reports: runAccessReport accepts either a property resource name (properties/123) or an account resource name (accounts/1234) to run access reports at the requested scope.

Typical entry points — what to call first

  • Discover accounts and properties: call the account summaries listing to quickly map which accounts you can access and which properties belong to them. Account summaries include property resource names, display names, and IDs—use them as the first step to locate a properties/{id} string needed by most other operations.

  • If you only have a Firebase project id or number, call the property listing with a filter (e.g. filter: "firebase_project:project-id" or filter: "firebase_project:123") to find the matching properties/{id}.

  • To operate on configuration inside a property, get the properties/{id} resource name first (from account summaries or properties.list with an appropriate filter) and pass it as parent to create/list calls (data streams, custom dimensions, conversion events, links, secrets).

Common tasks and the call sequences to accomplish them

The following patterns cover the workflows users ask about most often.

  • Create a Property (high level): construct the Property create body according to the API types and call the property creation operation. A created Property will be returned in the response body—use its name (properties/{id}) for subsequent calls.

  • Find a Property by account, ancestor, or Firebase project:

    • Use account summaries to locate properties under an account, or
    • Use properties.list with filter values like parent:accounts/123, ancestor:accounts/123, or firebase_project:project-id to find the properties/{id}.

  • Create a Data Stream and get its measurement secret:

    1. Create the stream with parent: properties/{id} via the data streams create operation. The response contains the data stream resource (and its resource name).
    2. Create a measurement protocol secret using the stream resource name as parent: properties/{property}/dataStreams/{dataStream}. To list existing secrets, call the secrets list with the same parent.

  • Manage custom dimensions and metrics:

    • List existing custom dimensions/metrics with parent: properties/{id}.
    • Create a new custom dimension/metric with parent: properties/{id} and the appropriate request body.
    • Update custom metrics with the patch operation; supply the full name (e.g. properties/1234/customMetrics/5678) and an updateMask listing fields to change (use "*" only if replacing the entire resource).
    • Archive a custom metric with its name using the archive operation—archiving is the supported way to retire custom metrics.

  • Create and manage conversion events: create them under parent: properties/{id} and list them with the same parent to confirm creation.

  • Link to Firebase or Google Ads:

    • Create the link with parent: properties/{id}. The response contains the link resource name; to remove a Firebase link, call delete with the link's full name.
    • List links under a property to discover link IDs before deleting.

  • Run an access report:

    • Decide the scope: pass either properties/{id} to run the report at the property level or accounts/{id} to run it across all properties in the account via the report endpoint's entity path parameter.
    • Build the report request body per the API types (dimensions, metrics, filters, date ranges) and inspect the response for rows and metadata.

Resource name patterns agents must supply verbatim

Always pass the full resource name string where the operation expects it. Typical patterns:

  • Account: accounts/{account}
  • Property: properties/{property}
  • Data stream: properties/{property}/dataStreams/{dataStream}
  • Custom metric/dimension: properties/{property}/customMetrics/{customMetric} or properties/{property}/customDimensions/{customDimension}
  • Firebase link: properties/{property}/firebaseLinks/{firebase_link}

If the operation signature names the parameter parent, provide the parent resource name (e.g. properties/123). If it names the parameter name, provide the full child resource name (e.g. properties/123/customMetrics/5678).

Pagination and size limits you need to know

  • Many list endpoints default to 50 items and accept up to 200 (the server will coerce higher values to the max). Measurement protocol secrets list is an exception: it defaults to 10 and its maximum is 10.
  • When you receive a nextPageToken, call the same list operation again with that token to fetch the next page. Provide the same other parameters when paginating (filters, parent, etc.).

Update semantics and fields to set carefully

  • Patch/update operations require an updateMask that names which fields change. Omit updateMask or pass it incorrectly and the fields you expect to change will not be updated. To replace the entire resource, use an update mask of "*".
  • Some create operations return the created resource in the response body but sign the type as the request body type in this surface; always inspect the response to get the authoritative resource name and server-assigned fields.

Non-obvious behaviors and gotchas

  • Full resource names, not numeric IDs: many callers mistakenly pass just the numeric ID. The API expects strings like properties/1234 or accounts/100. Confirm the value you pass matches the expected pattern in the operation's path parameter.

  • Scope of reports: runAccessReport accepts either a property or an account entity. Requesting an account-level report returns access events across all properties in that account—use this intentionally if broader scope is desired.

  • Soft-deleted resources: several list operations accept showDeleted to include soft-deleted (trashed) items. If a user expects to find a resource that seems missing, include showDeleted=true to verify whether it was trashed.

  • Archival vs deletion: CustomMetrics use an archive operation rather than delete. Expect archived metrics to remain visible only when explicitly querying for deleted/archived items (or by inspecting resource state fields).

  • Measurement protocol secrets are intentionally small in number: the list limit is 10. If a user asks to enumerate many secrets, expect at most 10 per stream.

  • Filters on property listing are powerful: the filter parameter supports parent:, ancestor:, and firebase_project: predicates. Use those to narrow results instead of listing all properties when the account has many.

  • Create operations sometimes require parent context in the request body or as a path parameter depending on the resource. If a create call fails for a missing parent, provide the properties/{id} parent string rather than a bare ID.

Quick sequences (cheat-sheet)

  • Discover property resource names you can act on: call account summaries -> read property name values.
  • Create a data stream and get its secret: create data stream under properties/{id} -> create measurement protocol secret with parent equal to the new stream's resource name.
  • Add a custom dimension/metric: call create with parent: properties/{id} -> list to confirm -> patch with full name and updateMask to adjust fields.
  • Link/unlink Firebase: create with parent: properties/{id} -> list to find link names -> delete by link name to unlink.
  • Run access report across an account: call run access report with entity: accounts/{id} and a report body describing dimensions/metrics/date ranges.

Follow these patterns: always obtain the full resource name for the scope you want to operate on first, pass that name as parent or name per the operation signature, and prefer list operations that return resource names (account summaries, properties.list, dataStreams.list) as the first step in a workflow.