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