Read an exact calendar-month GA4 report
/sites/{site_id}/ga4/monthly-reports/{report_type}analytics:readRead a completed calendar month from canonical storage. Use site_totals or summary_kpis for exact interval totals; sessions_over_time and audience_funnel retain daily rows. Never sum daily/page distinct users or sessions to approximate interval totals. Pending remains HTTP 200: inspect data.metadata.state and explicitly prepare if authorized. Default limit 100, maximum 500. Preserve report_set_id while paging an exact publication.
| Request | GET https://satelliteai.io/api/v1/sites/{site_id}/ga4/monthly-reports/{report_type} |
| Permission | analytics:read |
| Response | A single object: data is Ga4MonthlyData. |
| Operation ID | getGa4MonthlyReport |
More context and worked examples are in the developer guide.
Example request
curl --fail-with-body --get \
'https://satelliteai.io/api/v1/sites/123/ga4/monthly-reports/sessions_over_time' \
--data-urlencode 'month=2026-09' \
-H "Authorization: Bearer $SATELLITE_API_KEY"Replace the example IDs with values returned by the discovery endpoints. Example values are placeholders, not real records.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
site_idrequired | path | integer | Authorized site id. Parent and site grants must also match. min 1 · max 9223372036854775807 |
report_typerequired | path | string | Authorized report type. Parent and site grants must also match. |
monthrequired | query | string | Completed calendar month YYYY-MM in the connected GA4 property timezone. pattern ^[0-9]{4}-[0-9]{2}$ · example 2026-09 |
limit | query | integer | Maximum rows per page. Default 100, maximum 500. default 100 · min 1 · max 500 |
offset | query | integer | Zero-based row offset, default 0, maximum 100000. default 0 · min 0 · max 100000 |
report_set_id | query | integer | Optional ready publication ID; keep it while paging to pin the same exact report. min 1 |
Unknown or repeated query parameters return 400.
Data dictionary
Scoped result. Lists return pagination metadata; unavailable records return 404. Canonical publication for a completed calendar month. Daily report aliases retain daily rows; use site_totals or summary_kpis for interval totals. GET never prepares missing data. Pending reads remain HTTP 200; inspect metadata.state and metadata.aggregation.
[] marks an array element. nullable means the value can be null; treat it as unknown, not zero. always present means the key is always included in the object.
| Field | Type | Description |
|---|---|---|
data.columns | array of string | Ordered dimension and metric column names. |
data.rows | array of array of string | number | Row arrays aligned positionally with columns. |
data.metadata | object | Publication provenance. A pending/unsupported state is not a zero-traffic report. Additional publication metadata may be present. |
data.metadata.state | stringnullable | State. |
data.metadata.source | stringnullable | Source. |
data.metadata.binding_id | integernullable | Binding id. |
data.metadata.connection_revision | integernullable | Connection revision. |
data.metadata.property_id | stringnullable | Property id. |
data.metadata.timezone | stringnullable | Timezone. |
data.metadata.start | stringnullable | Start. |
data.metadata.end | stringnullable | End. |
data.metadata.dataset | stringnullable | Dataset. |
data.metadata.definition_version | integernullable | Definition version. |
data.metadata.report_set_id | integernullable | Report set id. |
data.metadata.report_state | stringnullable | Report state. |
data.metadata.fetched_at | stringnullable | Fetched at. |
data.metadata.total_rows | integernullable | Total rows. |
data.metadata.next_offset | integernullable | Next offset. |
data.metadata.aggregation | stringnullable | Aggregation. |
data.metadata.quality | array of object | Stored provider quality metadata. |
Response metadata
| Field | Type | Description |
|---|---|---|
meta.request_id | stringalways present | Request identifier; also returned in X-Request-ID. Include it in support requests. |
meta.api_version | stringalways present | API version that produced the response. one of: v1 |
meta.limit | integer | Maximum records per page applied to this request. min 1 · max 100 |
meta.has_more | boolean | True when another page is available. |
meta.next_cursor | stringnullable | Opaque cursor for the next page; send as cursor. Null on the last page. |
meta.availability | string | available when stored data exists; not_available when it does not. one of: available, not_available |
meta.billing | object | Present for paid live SERP requests; replayed receipts describe the original debit, not an additional charge. |
meta.billing.operation | stringalways present | one of: client_api_serp_refresh |
meta.billing.credits_charged | integeralways present | min 0 |
meta.billing.transaction_id | integeralways present | |
meta.billing.replayed | booleanalways present |
Error responses
Errors return {"error": {"code", "message", "request_id"}}. See error handling for retry guidance.
| HTTP | When |
|---|---|
400 | Invalid parameters |
401 | Invalid credentials |
403 | Missing permission |
404 | Missing or inaccessible resource |