Multihub Reporting API

The complete query grammar: arguments, operators, grains, aggregations, paging and errors.

The two operations

reporting_datasets — the catalog

Metadata only, no arguments. Returns every dataset with its dimensions and metrics. This is the authoritative list: names you can pass to reporting_data come from here, and the description fields carry each dataset's caveats.

{
  reporting_datasets {
    name
    description
    required_integrations
    last_refresh_at
    dimensions { id name type grains }
    metrics { name description unit aggregations default_aggregation supported_dimensions }
  }
}

reporting_data — the rows

Runs one query and returns aggregated rows. Pass the spec as GraphQL variables — filters, group_by, order_by and window are JSON values, so variables are cleaner than inlining them in the document.

query Pull($group: [JSON], $filters: [JSON], $order: [JSON]) {
  reporting_data(
    dataset:   "ga4_session_source_daily"
    metrics:   ["Sessions", "New Users"]
    group_by:  $group
    filters:   $filters
    order_by:  $order
    page_size: 5000
  ) {
    dataset
    rowCount
    totalRows
    bytesProcessed
    cacheHit
    cursor
    rows
  }
}

{
  "group":   ["property", "channel", {"dim": "date", "grain": "month"}],
  "filters": [
    {"dim": "date",    "op": ">=", "value": "2026-01-01"},
    {"dim": "channel", "op": "!=",   "value": "Unassigned"}
  ],
  "order":   [{"by": "Sessions", "dir": "desc"}]
}

Arguments

Metrics and aggregations

A metric is requested by its display name. Each has a default_aggregation that applies when you do not ask for one, and an aggregations list of everything it allows.

Not every metric allows every aggregation — aggregations in the catalog is the list, and anything outside it is rejected. Several metrics forbid sum outright and default to avg or max (the property-reference datasets, reputation scores, Woorank, and Search Console Position). count_distinct is not currently permitted by any metric in the catalog.

Ratio metrics (Paid CTR, Cost per Click, Engagement Rate…) accept only ratio, and are always computed as a ratio of sums — total clicks ÷ total impressions over the grouped rows — never an average of per-row ratios. That is the arithmetically correct rollup provided both the numerator and the denominator are additive at the row grain, which is the usual case.

Dimensions and grains

Three dimension types, with different rules:

Grains

A time dimension can be bucketed coarser than it is stored:

"group_by": [{"dim": "date", "grain": "month"}]

A grain on a non-time dimension is an error. So is a grain on the pre-bucketed ga4_users_* datasets — their rows already are the bucket.

Pre-bucketed datasets

Filters and operators

Each filter is {"dim": …, "op": …, "value": …}. Filters are AND-ed. Omit op and it defaults to =.

Text operator rules

• Category dimensions only. A text operator on date or on a tenancy dimension is rejected.
• A list means "any of", OR-ed within that one filter. Top-level filters stay AND-ed, so {"op":"STARTS_WITH","value":["brand","competitor"]} is a single "starts with either" condition.
• Values are literal. % and _ match themselves; there are no wildcards. Empty strings are rejected, because an empty needle silently matches everything.
• NOT_CONTAINS keeps null values. A row whose dimension is null does not contain your needle, so it survives the exclusion. That makes an CONTAINS / NOT_CONTAINS pair an exact partition of the rows.

Filtering on tenancy dimensions

Because a fact row can map to several entities, a tenancy filter matches a row if any of its entities match. The ids below are placeholders you supply — the companies query returns the ones your token can see:

[{"dim": "property", "op": "IN",
  "value": ["YOUR_PROPERTY_ID", "ANOTHER_PROPERTY_ID"]},
 {"dim": "company", "op": "=", "value": "YOUR_COMPANY_ID"}]

Ids are 16-character values and should be sent, stored and compared as strings — they are larger than a double represents exactly, so treating one as a number loses precision. Get them from the companies query. A tenancy filter narrows within your grants; it can never widen them.

Filtering on dates

Write dates as YYYY-MM-DD and they bind as real dates. A half-open range is the safest form — >= the first day, < the day after the last:

[{"dim":"date","op":">=","value":"2026-01-01"},
 {"dim":"date","op":"<", "value":"2026-07-01"}]

Ordering

order_by takes {"by": …, "dir": "asc"|"desc"}. dir defaults to desc. by must name a dimension you grouped by, or a metric you selected — using the metric's output name, so Average Sessions if you asked for avg. Anything else is an error.

"order_by": [{"by": "Paid Spend", "dir": "desc"}, {"by": "property", "dir": "asc"}]

Per-partition top-N

window ranks rows within each bucket — the top 3 cities for every property, the top 10 keywords per campaign — in one query.

"group_by": ["property", "city"],
"window": {
  "partition_by": ["property"],
  "order_by":     [{"by": "Sessions", "dir": "desc"}],
  "top_n":        3
}

Ties share a rank, so a partition can return more than top_n rows when values tie at the cutoff.

Top-N mode vs paginated mode

The two are mutually exclusive; sending both is an error. Sending neither gives you paginated mode with a page size of 10,000, which is what a bulk pull wants.

Paginated mode

The first call runs the query once and returns page 1 plus a cursor. Each follow-up call reads the next page of that same finished result — the query does not re-run, so later pages come back quickly and cannot shift under you when the nightly build replaces a table mid-pull.

A continuation request carries only cursor and optionally page_size. The cursor already identifies the dataset, metrics and filters; sending a spec alongside it is an error rather than a silently ignored change.

query Page($cursor: String) {
  reporting_data(cursor: $cursor, page_size: 5000) {
    rowCount totalRows cursor rows
  }
}

Loop while cursor is non-null. It is null on the last page.

• Cursors expire after 23 hours. An expired cursor returns a clear error; the remedy is to re-run the query from the start.
• Cursors are bound to the user who created them. Presenting one with a different account's token is refused.
• Treat a cursor as opaque. Its format is not a contract.

Response fields

Errors

Errors come back in GraphQL's errors array with a code in extensions.code. The message is specific — it names the dataset, dimension or metric at fault — so log it.

An expired cursor also carries extensions.reportingStatus: 410, which lets a sync job distinguish "start this pull again" from "this request was malformed" without parsing the message.