Skip to content
Ads API •References / Reports / Create Report

Create Report

Returns ad performance data based on selected parameters.

Request

POST
/report

The request for creating a report or fetching the next page of report data. If the continuation_token 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 page_size is 200.

  • dimensions
    array of Reporting Dimension Type

    Specify how the retrieved data should be organized.

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

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

    Example value: "CLICKS"Allowed values: "CLICKS", "COMPLETES", "COMPLETION_RATE", "CONVERSION_RATE", "CTR", "ECPCL", "ECPM", "ERRORS", "FETCHES", "FETCH_REACH", "FIRST_QUARTILES", "IMPRESSIONS", "INTENT_RATE", "LISTENERS", "MIDPOINTS", "NEW_LISTENERS", "NEW_LISTENER_CONVERSION_RATE", "NEW_LISTENER_STREAMS", "OFF_SPOTIFY_IMPRESSIONS", "PAID_LISTENS", "PAID_LISTEN_FREQ", "PAID_LISTEN_REACH", "RENDER_RATIO", "SERVES", "SERVE_FREQ", "SERVE_REACH", "SKIPS", "SPEND", "STARTS", "STREAMS", "STREAMS_PER_NEW_LISTENER", "STREAMS_PER_USER", "THIRD_QUARTILES"
  • organization_ids
    array of strings
  • ad_account_ids
    array of strings
  • continuation_token
    string
  • page_size
    integer
    Example value: 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.

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          }        ]      }    ]  }}