Skip to content
Ads API •References / Reports / Create Report by Ad Account

Create Report by Ad Account

Returns ad performance data for a specific ad account based on selected parameters.

Request

  • ad_account_id
    string [uuid]
    Required

The request for creating a report or fetching the next page of report data.

If the continuationToken field is specified, then the other properties are ignored and the token is used to fetch the next page of results associated with the token.

The default pageSize is 200.

    • campaign_ids
      array of strings
    • ad_set_ids
      array of strings
    • ad_ids
      array of strings
    • advertiser_ids
      array of strings
    • country_isos
      array of strings
      Example: "US"
    • region_ids
      array of integers
    • dma_ids
      array of integers
    • platforms
      array of Platform
      Example: ["IOS"]
      Allowed values: "IOS", "DESKTOP", "ANDROID", "OTHER"Example: "IOS"
    • campaign_statuses
      array of Campaign Status
      Example: ["ACTIVE"]
      Allowed values: "ACTIVE", "PAUSED", "ARCHIVED"Example: "ACTIVE"
    • ad_set_statuses
      array of Ad Set Status
      Example: ["ACTIVE"]
      Allowed values: "ACTIVE", "APPROVED", "ARCHIVED", "COMPLETED", "PENDING_APPROVAL", "READY", "REJECTED"Example: "ACTIVE"
    • ad_set_start_dates
      array of strings
    • ad_set_end_dates
      array of strings
    • cost_type_filters
      array of Ad Set Cost Model
      Example: ["CPM"]
      Allowed values: "CPCL", "CPM", "CPC", "UNSET"Example: "CPCL"
      • report_start
        string [date-time]
        Required

        Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset (YYYY-MM-DDTHH:MM:SSZ) and must be expressed in whole hours (0 minutes and 0 seconds). NOTE: Hours are inclusive, which means that requesting T00:00:00 – T23:00:00, for example, will return data for the full 24 hours (from T23:00:00 through T23:59:59).

        Example: "2022-08-24T14:15:22Z"
      • report_end
        string [date-time]
        Required

        Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset (YYYY-MM-DDTHH:MM:SSZ) and must be expressed in whole hours (0 minutes and 0 seconds). NOTE: Hours are inclusive, which means that requesting T00:00:00 – T23:00:00, for example, will return data for the full 24 hours (from T23:00:00 through T23:59:59).

        Example: "2022-09-24T14:15:22Z"
  • dimensions
    array of Reporting Dimension Type

    Specify how the retrieved data should be organized.

    Allowed values: "CAMPAIGN", "AD_SET", "AD", "ADVERTISER", "YEAR", "MONTH", "DAY", "HOUR", "COUNTRY", "REGION", "DMA", "PLATFORM", "CURRENCY", "COST_TYPE"Example: "CAMPAIGN"
  • fields
    array of Reporting Field Type

    Refer to the Metrics Glossary section for definitions of each field.

    Allowed values: "FETCHES", "STARTS", "FIRST_QUARTILES", "MIDPOINTS", "THIRD_QUARTILES", "COMPLETES", "IMPRESSIONS", "CLICKS", "SKIPS", "ERRORS", "SERVES", "PAID_LISTEN_REACH", "SERVE_REACH", "SERVE_FREQ", "PAID_LISTENS", "PAID_LISTEN_FREQ", "COMPLETION_RATE", "SPEND", "CTR", "RENDER_RATIO", "FETCH_REACH", "STREAMS", "NEW_LISTENER_STREAMS", "LISTENERS", "NEW_LISTENERS", "INTENT_RATE", "CONVERSION_RATE", "NEW_LISTENER_CONVERSION_RATE", "STREAMS_PER_NEW_LISTENER", "STREAMS_PER_USER", "OFF_SPOTIFY_IMPRESSIONS"Example: "FETCHES"
  • organization_ids
    array of strings
  • ad_account_ids
    array of strings
  • continuation_token
    string
  • page_size
    integer
    Example: 2

Response

The response object.

If there is another page of results, the continuationToken property will be populated. Otherwise, it will be null.

The page property contains the page results.

  • continuation_token
    string
  • The report page consists of 1 property:

    • rows: The page results.

    Each row is an object that contains the dimension values (in the dimensions array) and the metrics values (in the fields array).

    Dimensions

    To determine the value of a dimension, check its "type" property.

    For example: If the value of the "type" property is "Ad Set", then check the "ad_set_dimension_value" property to get the dimension value. The other value properties will be null.

    Fields

    Each field consists of a type and a value.

    For ex: If you query for the number of lifetime clicks on a given ad set, you will get back an array of fields with a single object. The object would have a property called type which would be "CLICKS", and a "value" equal to the number of clicks.

        • type
          string [reporting-dimension-type]
          Allowed values: "CAMPAIGN", "AD_SET", "AD", "ADVERTISER", "YEAR", "MONTH", "DAY", "HOUR", "COUNTRY", "REGION", "DMA", "PLATFORM", "CURRENCY", "COST_TYPE"Example: "CAMPAIGN"
          • timestamp
            string [date-time]
            Example: "2022-01-23T04:56:07Z"
          • name
            string
          • country_iso
            string
            Example: "US"
          • platform
            string [platform]
            Allowed values: "IOS", "DESKTOP", "ANDROID", "OTHER"Example: "IOS"
          • id
            string [uuid]
          • name
            string
          • current_status
            string [ad-status]
            Allowed values: "ACTIVE", "PENDING", "PENDING_USER_APPROVAL", "PENDING_ADMIN_APPROVAL", "APPROVED", "REJECTED", "ARCHIVED", "UNRECOGNIZED"Example: "ACTIVE"
          • id
            string [uuid]
          • name
            string
          • current_status
            string [campaign-status]
            Allowed values: "UNSET", "ACTIVE", "PAUSED", "ARCHIVED", "UNRECOGNIZED"Example: "ACTIVE"
          • id
            string [uuid]
          • name
            string
          • start_date
            string [date-time]
          • end_date
            string [date-time]
          • current_status
            string [ad-set-status]
            Allowed values: "ACTIVE", "APPROVED", "ARCHIVED", "COMPLETED", "PENDING_APPROVAL", "READY", "REJECTED"Example: "ACTIVE"
          • current_budget_micros
            integer [int64]
          • currency
            string
          • cost_type
            string [ad-set-cost-model]
            Allowed values: "CPCL", "CPM", "CPC", "UNSET"Example: "CPCL"
          • id
            integer
          • name
            string
          • name
            string
          • currency_iso
            string
          • id
            string [uuid]
          • name
            string
          • id
            integer
          • name
            string
          • cost_type
            string [ad-set-cost-model]
            Allowed values: "CPCL", "CPM", "CPC", "UNSET"Example: "CPCL"
        • type
          string [reporting-field-type]
          Allowed values: "FETCHES", "STARTS", "FIRST_QUARTILES", "MIDPOINTS", "THIRD_QUARTILES", "COMPLETES", "IMPRESSIONS", "CLICKS", "SKIPS", "ERRORS", "SERVES", "PAID_LISTEN_REACH", "SERVE_REACH", "SERVE_FREQ", "PAID_LISTENS", "PAID_LISTEN_FREQ", "COMPLETION_RATE", "SPEND", "CTR", "RENDER_RATIO", "FETCH_REACH", "STREAMS", "NEW_LISTENER_STREAMS", "LISTENERS", "NEW_LISTENERS", "INTENT_RATE", "CONVERSION_RATE", "NEW_LISTENER_CONVERSION_RATE", "STREAMS_PER_NEW_LISTENER", "STREAMS_PER_USER", "OFF_SPOTIFY_IMPRESSIONS"Example: "FETCHES"
        • value
          number [double]

Response sample

{  "continuation_token": "continuation_token",  "page": {    "rows": [      {        "dimensions": [          {            "type": "CAMPAIGN",            "timestamp_dimension_value": {              "timestamp": "2022-01-23T04:56:07.000+00:00"            },            "country_dimension_value": {              "name": "United States of America",              "country_iso": "US"            },            "platform_dimension_value": {              "platform": "IOS"            },            "ad_dimension_value": {              "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",              "name": "Ad name",              "current_status": "ACTIVE"            },            "campaign_dimension_value": {              "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",              "name": "Campaign name",              "current_status": "ACTIVE"            },            "ad_set_dimension_value": {              "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",              "name": "Ad Set Name",              "start_date": "2022-01-23T04:56:07.000+00:00",              "end_date": "2022-02-23T04:56:07.000+00:00",              "current_status": "ACTIVE",              "current_budget_micros": 2500000000,              "currency": "USD",              "cost_type": "CPM"            },            "dma_dimension_value": {              "id": "id",              "name": "name"            },            "currency_dimension_value": {              "name": "name",              "currency_iso": "currency_iso"            },            "advertiser_dimension_value": {              "id": "id",              "name": "name"            },            "region_dimension_value": {              "id": "id",              "name": "name"            },            "cost_type_dimension_value": {              "cost_type": "CPM"            }          },          {            "type": "CAMPAIGN",            "timestamp_dimension_value": {              "timestamp": "2022-01-23T04:56:07.000+00:00"            },            "country_dimension_value": {              "name": "United States of America",              "country_iso": "US"            },            "platform_dimension_value": {              "platform": "IOS"            },            "ad_dimension_value": {              "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",              "name": "Ad name",              "current_status": "ACTIVE"            },            "campaign_dimension_value": {              "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",              "name": "Campaign name",              "current_status": "ACTIVE"            },            "ad_set_dimension_value": {              "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",              "name": "Ad Set Name",              "start_date": "2022-01-23T04:56:07.000+00:00",              "end_date": "2022-02-23T04:56:07.000+00:00",              "current_status": "ACTIVE",              "current_budget_micros": 2500000000,              "currency": "USD",              "cost_type": "CPM"            },            "dma_dimension_value": {              "id": "id",              "name": "name"            },            "currency_dimension_value": {              "name": "name",              "currency_iso": "currency_iso"            },            "advertiser_dimension_value": {              "id": "id",              "name": "name"            },            "region_dimension_value": {              "id": "id",              "name": "name"            },            "cost_type_dimension_value": {              "cost_type": "CPM"            }          }        ],        "fields": [          {            "type": "COMPLETES",            "value": 100          },          {            "type": "COMPLETES",            "value": 100          }        ]      },      {        "dimensions": [          {            "type": "CAMPAIGN",            "timestamp_dimension_value": {              "timestamp": "2022-01-23T04:56:07.000+00:00"            },            "country_dimension_value": {              "name": "United States of America",              "country_iso": "US"            },            "platform_dimension_value": {              "platform": "IOS"            },            "ad_dimension_value": {              "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",              "name": "Ad name",              "current_status": "ACTIVE"            },            "campaign_dimension_value": {              "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",              "name": "Campaign name",              "current_status": "ACTIVE"            },            "ad_set_dimension_value": {              "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",              "name": "Ad Set Name",              "start_date": "2022-01-23T04:56:07.000+00:00",              "end_date": "2022-02-23T04:56:07.000+00:00",              "current_status": "ACTIVE",              "current_budget_micros": 2500000000,              "currency": "USD",              "cost_type": "CPM"            },            "dma_dimension_value": {              "id": "id",              "name": "name"            },            "currency_dimension_value": {              "name": "name",              "currency_iso": "currency_iso"            },            "advertiser_dimension_value": {              "id": "id",              "name": "name"            },            "region_dimension_value": {              "id": "id",              "name": "name"            },            "cost_type_dimension_value": {              "cost_type": "CPM"            }          },          {            "type": "CAMPAIGN",            "timestamp_dimension_value": {              "timestamp": "2022-01-23T04:56:07.000+00:00"            },            "country_dimension_value": {              "name": "United States of America",              "country_iso": "US"            },            "platform_dimension_value": {              "platform": "IOS"            },            "ad_dimension_value": {              "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",              "name": "Ad name",              "current_status": "ACTIVE"            },            "campaign_dimension_value": {              "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",              "name": "Campaign name",              "current_status": "ACTIVE"            },            "ad_set_dimension_value": {              "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",              "name": "Ad Set Name",              "start_date": "2022-01-23T04:56:07.000+00:00",              "end_date": "2022-02-23T04:56:07.000+00:00",              "current_status": "ACTIVE",              "current_budget_micros": 2500000000,              "currency": "USD",              "cost_type": "CPM"            },            "dma_dimension_value": {              "id": "id",              "name": "name"            },            "currency_dimension_value": {              "name": "name",              "currency_iso": "currency_iso"            },            "advertiser_dimension_value": {              "id": "id",              "name": "name"            },            "region_dimension_value": {              "id": "id",              "name": "name"            },            "cost_type_dimension_value": {              "cost_type": "CPM"            }          }        ],        "fields": [          {            "type": "COMPLETES",            "value": 100          },          {            "type": "COMPLETES",            "value": 100          }        ]      }    ]  }}