List Ads entity catalog

GET/sites/{site_id}/google-ads/accounts/{account_id}/entities/{entity_type}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}/entities/{entity_type}`
Permission	`google-ads:read`
Response	A list (cursor or offset paginated): `data` is `array of GoogleAdsEntity`.
Operation ID	`listGoogleAdsEntities`

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/entities/ad-groups' \
  -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
`entity_type`required	path	string	one of: ad-groups, ads, asset-groups, keywords · example ad-groups
`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
`campaign_id`	query	string	Assigned Google campaign ID, signed 64-bit positive decimal string. Inaccessible campaign returns 404. pattern ^[0-9]{1,19}$
`include_removed`	query	string	Include historical removed catalog records. Historical reports remain readable. one of: true, false · default false

Unknown or repeated query parameters return 400.

RESPONSE

Data dictionary

Stored site-assigned results. No provider refresh or credit debit. Entity fields depend on entity_type; only the applicable catalog fields are returned. Provider identifiers are decimal strings.

[] 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[].site_id`	integernullablealways present	Satellite site ID (from GET /sites).
`data[].account_id`	integernullablealways present
`data[].campaign_id`	stringnullablealways present	Decimal string preserving full Google identifier or micros precision. max length 4096 · pattern ^[0-9]+$
`data[].ad_group_id`	stringnullable	Decimal string preserving full Google identifier or micros precision. max length 4096 · pattern ^[0-9]+$
`data[].name`	stringnullable	max length 4096
`data[].status`	stringnullablealways present	max length 4096
`data[].type`	stringnullable	max length 4096
`data[].cpc_bid_micros`	stringnullable	Decimal string preserving full Google identifier or micros precision. max length 4096 · pattern ^[0-9]+$
`data[].target_cpa_micros`	stringnullable	Decimal string preserving full Google identifier or micros precision. max length 4096 · pattern ^[0-9]+$
`data[].target_roas`	numbernullable
`data[].first_seen_at`	string (date-time)nullablealways present	max length 4096
`data[].last_seen_at`	string (date-time)nullablealways present	max length 4096
`data[].removed_at`	string (date-time)nullablealways present	max length 4096
`data[].ad_id`	stringnullable	Decimal string preserving full Google identifier or micros precision. max length 4096 · pattern ^[0-9]+$
`data[].asset_group_id`	stringnullable	Decimal string preserving full Google identifier or micros precision. max length 4096 · pattern ^[0-9]+$
`data[].criterion_id`	stringnullable	Decimal string preserving full Google identifier or micros precision. max length 4096 · pattern ^[0-9]+$
`data[].keyword_text`	stringnullable	max length 4096
`data[].match_type`	stringnullable	max length 4096
`data[].negative`	booleannullable
`data[].quality_score`	integernullable
`data[].creative_quality`	stringnullable	max length 4096
`data[].post_click_quality`	stringnullable	max length 4096
`data[].search_predicted_ctr`	stringnullable	max length 4096
`data[].first_page_cpc_micros`	stringnullable	Decimal string preserving full Google identifier or micros precision. max length 4096 · pattern ^[0-9]+$
`data[].top_of_page_cpc_micros`	stringnullable	Decimal string preserving full Google identifier or micros precision. max length 4096 · pattern ^[0-9]+$
`data[].first_position_cpc_micros`	stringnullable	Decimal string preserving full Google identifier or micros precision. max length 4096 · pattern ^[0-9]+$

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.