CLIENT API / V1 GOOGLE ADS

Read stored Ads metrics

GET/sites/{site_id}/google-ads/accounts/{account_id}/reports/{report_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. Summary and daily roll up campaign facts only; summary rejects pagination. All other reports use limit/offset.

RequestGET https://satelliteai.io/api/v1/sites/{site_id}/google-ads/accounts/{account_id}/reports/{report_type}
Permissiongoogle-ads:read
ResponseA single object: data is GoogleAdsReport.
Operation IDgetGoogleAdsReport

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/reports/summary' \
  -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

NameInTypeDescription
site_idrequiredpathintegerID from GET /sites.
min 1
account_idrequiredpathintegerSatellite account ID from /google-ads/accounts; not the Google customer ID.
min 1 · max 2147483647 · example 12
report_typerequiredpathstring
one of: summary, daily, campaigns, ad-groups, ads, asset-groups, keywords, search-terms, landing-pages, conversions, geography · example summary
start_datequerystring (date)Paired inclusive account-local dates, at most 1131 dates. Default last 30 completed account-local dates, excluding today.
end_datequerystring (date)Paired inclusive account-local dates, at most 1131 dates. Default last 30 completed account-local dates, excluding today.
limitqueryinteger
default 50 · min 1 · max 100
offsetqueryintegerBounded offset; next_offset is null at the cap. Mutable stored data is not an atomic pagination snapshot.
default 0 · min 0 · max 100000
campaign_idquerystringAssigned Google campaign ID, signed 64-bit positive decimal string. Inaccessible campaign returns 404.
pattern ^[0-9]{1,19}$
url_kindquerystringOnly landing-pages. One URL variant per request; variants overlap.
one of: expanded, unexpanded · default expanded
location_typequerystringOnly geography. One location variant per request; variants overlap.
one of: physical, area_of_interest · default physical

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.

FieldTypeDescription
data.site_idintegeralways presentSatellite site ID (from GET /sites).
data.account_idintegeralways present
data.customer_idstringalways present
max length 4096
data.report_typestringalways present
one of: summary, daily, campaigns, ad-groups, ads, asset-groups, keywords, search-terms, landing-pages, conversions, geography · max length 4096
data.sourcestringalways present
one of: stored · max length 4096
data.time_zonestringalways present
max length 4096
data.date_rangeobjectalways present
data.date_range.start_datestring (date)always present
max length 4096
data.date_range.end_datestring (date)always present
max length 4096
data.rowsarray of GoogleAdsMetricRowalways present
max items 100
data.rows[].account_idintegeralways present
data.rows[].datestring (date)nullablealways present
max length 4096
data.rows[].campaign_idstringnullablealways present
max length 4096 · pattern ^[0-9]+$
data.rows[].campaign_namestringnullablealways present
max length 4096
data.rows[].currency_codestringalways presentCurrency of this row. Never combine different currencies.
max length 4096
data.rows[].fetched_atstring (date-time)nullablealways presentWhen Satellite fetched the data from its source (UTC, RFC 3339).
max length 4096
data.rows[].dimensionsobjectalways present
data.rows[].dimensions.devicestringnullable
max length 4096
data.rows[].dimensions.ad_network_typestringnullable
max length 4096
data.rows[].dimensions.ad_group_idstringnullable
max length 4096 · pattern ^[0-9]+$
data.rows[].dimensions.ad_idstringnullable
max length 4096 · pattern ^[0-9]+$
data.rows[].dimensions.asset_group_idstringnullable
max length 4096 · pattern ^[0-9]+$
data.rows[].dimensions.criterion_idstringnullable
max length 4096 · pattern ^[0-9]+$
data.rows[].dimensions.search_term_idstringnullable
max length 4096 · pattern ^[0-9]+$
data.rows[].dimensions.match_typestringnullable
max length 4096
data.rows[].dimensions.source_viewstringnullable
max length 4096
data.rows[].dimensions.landing_url_idstringnullable
max length 4096 · pattern ^[0-9]+$
data.rows[].dimensions.url_kindstringnullable
max length 4096
data.rows[].dimensions.conversion_action_idstringnullable
max length 4096 · pattern ^[0-9]+$
data.rows[].dimensions.geo_target_idstringnullable
max length 4096 · pattern ^[0-9]+$
data.rows[].dimensions.location_typestringnullable
max length 4096
data.rows[].dimensions.keyword_textstringnullable
max length 4096
data.rows[].dimensions.quality_scoreintegernullable
data.rows[].dimensions.search_termstringnullable
max length 4096
data.rows[].dimensions.landing_urlstringnullable
max length 2048
data.rows[].dimensions.page_idintegernullableSatellite page ID (from GET /sites/{site_id}/pages).
data.rows[].dimensions.conversion_action_namestringnullable
max length 4096
data.rows[].dimensions.geo_namestringnullable
max length 4096
data.rows[].dimensions.country_codestringnullable
max length 4096
data.rows[].impressionsintegernullablealways present
data.rows[].clicksintegernullablealways present
data.rows[].cost_microsstringnullablealways presentCost in millionths of the row currency, serialized as an integer decimal string.
max length 4096 · pattern ^-?[0-9]+(?:\.[0-9]{6})?$
data.rows[].interactionsintegernullablealways present
data.rows[].view_through_conversionsintegernullablealways present
data.rows[].conversionsnumbernullablealways present
data.rows[].conversions_valuestringnullablealways presentConversion value in the row currency; six decimal places. Unknown remains null.
max length 4096 · pattern ^-?[0-9]+(?:\.[0-9]{6})?$
data.rows[].all_conversionsnumbernullablealways present
data.rows[].all_conversions_valuestringnullablealways presentConversion value in the row currency; six decimal places. Unknown remains null.
max length 4096 · pattern ^-?[0-9]+(?:\.[0-9]{6})?$
data.rows[].coststringnullablealways presentCost in currency units, six decimal places.
max length 4096 · pattern ^-?[0-9]+(?:\.[0-9]{6})?$
data.rows[].cpcstringnullablealways presentCost per click in currency units, null if denominator is zero or unknown.
max length 4096 · pattern ^-?[0-9]+(?:\.[0-9]{6})?$
data.rows[].ctrnumbernullablealways presentClicks / impressions, a fraction (0.1 = 10%).
data.rows[].conversion_ratenumbernullablealways presentConversions / interactions, a fraction.
data.rows[].roasnumbernullablealways presentConversion value / cost, a multiplier.
data.rows[].search_impression_sharenumbernullablealways presentStored campaign grain share; null in summary/daily rollups. Never sum or average shares across rows.
data.rows[].search_budget_lost_impression_sharenumbernullablealways presentStored campaign grain share; null in summary/daily rollups. Never sum or average shares across rows.
data.rows[].search_rank_lost_impression_sharenumbernullablealways presentStored campaign grain share; null in summary/daily rollups. Never sum or average shares across rows.
data.rows[].truncated_fieldsarray of stringalways presentFields shortened or omitted because they exceeded public size limits.
max items 30
data.coverageobjectalways presentCollection coverage is account-wide, not a site row count. Missing dates are not zeros; rebuilding suppresses facts. A committed window remains valid if its containing sync is still running or later fails.
data.coverage.collection_scopestringalways present
one of: account · max length 4096
data.coverage.report_scopestringalways present
one of: site · max length 4096
data.coverage.periodsarray of objectalways present
max items 1131
data.coverage.periods[].datestring (date)always present
max length 4096
data.coverage.periods[].statusstringalways presentcomplete, empty, failed, partial, or another stored collection status.
max length 4096
data.coverage.periods[].fetched_atstring (date-time)nullablealways presentWhen Satellite fetched the data from its source (UTC, RFC 3339).
max length 4096
data.coverage.missing_datesarray of string (date)always present
max items 1131
data.coverage.completebooleanalways present
data.coverage.rebuild_pendingbooleanalways present
data.restatement_noticestringalways present
max length 4096

Response metadata

FieldTypeDescription
meta.request_idstringalways presentRequest identifier; also returned in X-Request-ID. Include it in support requests.
meta.api_versionstringalways presentAPI version that produced the response.
one of: v1
meta.limitintegerMaximum records per page applied to this request.
min 1 · max 100
meta.has_morebooleanTrue when another page is available.
meta.next_cursorstringnullableOpaque cursor for the next page; send as cursor. Null on the last page.
meta.availabilitystringavailable when stored data exists; not_available when it does not.
one of: available, not_available
meta.sourcestringalways present
one of: stored · max length 4096
meta.access_scopestring
one of: site · max length 4096
meta.connection_statusstring
max length 128
meta.offsetinteger
min 0 · max 100000
meta.next_offsetintegernullable
min 0 · max 100000
meta.offset_limit_reachedboolean
ERRORS

Error responses

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

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