Read account collection coverage

GET/sites/{site_id}/google-ads/accounts/{account_id}/coverage/{dataset}google-ads:read

OVERVIEW

Requires google-ads:read. Stored reads only: no source=live, refresh, GAQL, provider account overrides, jobs, or credit charges. Explicit site grants and current campaign assignments constrain reports. Shared account collection coverage never grants other-site metrics.

Request	`GET https://satelliteai.io/api/v1/sites/{site_id}/google-ads/accounts/{account_id}/coverage/{dataset}`
Permission	`google-ads:read`
Response	A list (cursor or offset paginated): `data` is `array of GoogleAdsCoveragePeriod`.
Operation ID	`listGoogleAdsCoverage`

More context and worked examples are in the developer guide.

REQUEST

Example request

cURL · Bash

curl --fail-with-body \
  'https://satelliteai.io/api/v1/sites/123/google-ads/accounts/12/coverage/campaigns' \
  -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_id`required	path	integer	ID from GET /sites. min 1
`account_id`required	path	integer	Satellite account ID from /google-ads/accounts; not the Google customer ID. min 1 · max 2147483647 · example 12
`dataset`required	path	string	one of: campaigns, ad-groups, ads, asset-groups, keywords, search-terms, landing-pages, conversions, geography · example campaigns
`start_date`	query	string (date)	Paired inclusive account-local dates, at most 1131 dates. Default last 30 completed account-local dates, excluding today.
`end_date`	query	string (date)	Paired inclusive account-local dates, at most 1131 dates. Default last 30 completed account-local dates, excluding today.
`limit`	query	integer	default 50 · min 1 · max 100
`offset`	query	integer	Bounded offset; next_offset is null at the cap. Mutable stored data is not an atomic pagination snapshot. default 0 · min 0 · max 100000

Unknown or repeated query parameters return 400.

RESPONSE

Data dictionary

Stored site-assigned results. No provider refresh or credit debit.

[] 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.

Fields in data
Field	Type	Description
`data[].date`	string (date)always present	max length 4096
`data[].status`	stringalways present	complete, empty, failed, partial, or another stored collection status. max length 4096
`data[].fetched_at`	string (date-time)nullablealways present	When Satellite fetched the data from its source (UTC, RFC 3339). max length 4096
`data[].dataset`	stringalways present	one of: campaigns, ad-groups, ads, asset-groups, keywords, search-terms, landing-pages, conversions, geography · max length 4096
`data[].collection_scope`	stringalways present	one of: account · max length 4096

Response metadata

Fields in meta
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.source`	stringalways present	one of: stored · max length 4096
`meta.access_scope`	string	one of: site · max length 4096
`meta.connection_status`	string	max length 128
`meta.offset`	integer	min 0 · max 100000
`meta.next_offset`	integernullable	min 0 · max 100000
`meta.offset_limit_reached`	boolean

ERRORS

Error responses

Errors return {"error": {"code", "message", "request_id"}}. See error handling for retry guidance.

HTTP	When
`400`	Unknown/repeated query, invalid filter or dates. summary rejects limit/offset; variant filters are only accepted by their corresponding report.
`401`	Missing, invalid, expired, or revoked credential.
`403`	Required explicit scope, active integration, or company API access unavailable.
`404`	Missing or inaccessible site, account, campaign, report, entity type, or dataset.
`409`	google_ads_timezone_unavailable: stored account time zone needs correction.
`413`	Response too large.
`429`	Request allowance exceeded; honor Retry-After.
`503`	Stored reporting or authentication temporarily unavailable.