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