Sign in
Ad reports

Retrieve ad report

Performance report for a company, ad campaigns, ad groups, or ads. Always returns aggregate summary totals summed across the scope. Set granularity to additionally get a time series, or set breakdown (campaign/ad_group/ad) to additionally get per-entity rows inside the requested scope. Exactly one of companyId, adCampaignIds, adGroupIds, or adIds must be provided.

Required permissions:

  • ad_campaign:stats:read
get/ad_reports

Query parameters

ad_campaign_idsstring[]

Scope the report to these ad campaigns (max 100); stats are summed across them. Mutually exclusive with companyId, adGroupIds, and adIds.

ad_group_idsstring[]

Scope the report to these ad groups (max 100); stats are summed across them. Mutually exclusive with companyId, adCampaignIds, and adIds.

ad_idsstring[]

Scope the report to these ads (max 100); stats are summed across them. Mutually exclusive with companyId, adCampaignIds, and adGroupIds.

breakdown'campaign' | 'ad_group' | 'ad'

Entity level to group an ad report by.

company_idstring

The unique identifier of a company. Mutually exclusive with adCampaignIds, adGroupIds, and adIds. Use with breakdown to fan out across every campaign, ad group, or ad in the company without paging.

Example:biz_xxxxxxxxxxxxxx
currencystring

ISO 4217 currency code to report spend in. Defaults to the company's ads reporting currency.

fromstring date-time required

Inclusive start of the reporting window.

Example:2023-12-01T05:00:00.401Z
granularity'hourly' | 'daily' | 'weekly' | 'monthly'

Bucket size for external ad stat rows.

tostring date-time required

Inclusive end of the reporting window.

Example:2023-12-01T05:00:00.401Z

Response

A successful response

Example response

{
  "breakdown": [
    {
      "granularity": [
        {
          "bucket_start": "2023-12-01T05:00:00.401Z",
          "clicks": 42,
          "impressions": 42,
          "reach": 42,
          "result_count": 42,
          "spend": 6.9,
          "stat_date": "2023-12-01T05:00:00.401Z",
          "stat_hour": 42
        }
      ],
      "summary": {
        "click_through_rate": 6.9,
        "clicks": 42,
        "cost_per_click": 6.9,
        "cost_per_mille": 6.9,
        "cost_per_result": 6.9,
        "frequency": 6.9,
        "impressions": 42,
        "reach": 42,
        "result_count": 42,
        "return_on_ad_spend": 6.9,
        "spend": 6.9
      }
    }
  ],
  "granularity": [
    {
      "bucket_start": "2023-12-01T05:00:00.401Z",
      "clicks": 42,
      "impressions": 42,
      "reach": 42,
      "result_count": 42,
      "spend": 6.9,
      "stat_date": "2023-12-01T05:00:00.401Z",
      "stat_hour": 42
    }
  ],
  "summary": {
    "click_through_rate": 6.9,
    "clicks": 42,
    "cost_per_click": 6.9,
    "cost_per_mille": 6.9,
    "cost_per_result": 6.9,
    "frequency": 6.9,
    "impressions": 42,
    "reach": 42,
    "result_count": 42,
    "return_on_ad_spend": 6.9,
    "spend": 6.9
  }
}

Changes

Changed in 1 of the 41 revisions of this API.29

  • f67a043e319029See the full diff
    • ▲

      the query request parameter breakdown was restricted to a list of enum values

      request-parameter-became-enum

    • ▲

      the query request parameter granularity was restricted to a list of enum values

      request-parameter-became-enum

    • ○

      added the new enum value ad to the query request parameter breakdown

      request-parameter-enum-value-added

    • ○

      added the new enum value ad_group to the query request parameter breakdown

      request-parameter-enum-value-added

    • ○

      added the new enum value campaign to the query request parameter breakdown

      request-parameter-enum-value-added

    • ○

      added the new enum value daily to the query request parameter granularity

      request-parameter-enum-value-added

    • ○

      added the new enum value hourly to the query request parameter granularity

      request-parameter-enum-value-added

    • ○

      added the new enum value monthly to the query request parameter granularity

      request-parameter-enum-value-added

    • ○

      added the new enum value weekly to the query request parameter granularity

      request-parameter-enum-value-added

    • ○

      for the query request parameter breakdown, the type/format was generalized from / to string/

      request-parameter-type-generalized

    • ○

      for the query request parameter granularity, the type/format was generalized from / to string/

      request-parameter-type-generalized