Skip to content
Ads API •References / reports / Create a CSV Report Asynchronously

Create a CSV Report Asynchronously

Create a CSV report asynchronously. The status of the CSV generation and the CSV itself (once available) can be found either in the 'Reports' section of Spotify Ads Manager or from the Get Async Report endpoint.

Request

  • ad_account_id
    string [uuid]
    Required

    A unique identifier for an Ad Account.

    Example: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a
  • name
    string
    Required

    Users can define the report name. It must be between 2 and 120 characters long and can't contain any special characters except for "_" and "-".

    Example: "My Report"
  • granularity
    string
    Required

    Reporting granularity for time breakdowns. Supported values are LIFETIME and DAY. For DAY, each row of the report for the primary entity will contain time series data within the range of report_start and report_end broken down by day.

    Default: "LIFETIME"Allowed values: "DAY", "LIFETIME"Example: "LIFETIME"
  • dimensions
    array of strings
    Required

    Users can define a set of dimensions that they would like populated as columns in the report. The primary entity of the data displayed in the report will be determined by the lowest level of the selected dimensions. The hierarchy of dimensions is Ad Account -> Campaign -> Ad Set -> Ad. For example, If the user selects AD_ACCOUNT_NAME the primary entity will be the Ad Account. If the user selects AD_ACCOUNT_NAME and CAMPAIGN_NAME, the primary entity will be the Campaign. If the user selects AD_SET_NAME and CAMPAIGN_NAME, the primary entity will be the Ad Set. If the user selects CAMPAIGN_NAME, AD_SET_NAME and AD_NAME, the primary entity will be the Ad.

    Example: ["CAMPAIGN_NAME","AD_SET_NAME"]
    Allowed values: "AD_ACCOUNT_NAME", "AD_ACCOUNT_CURRENCY", "CAMPAIGN_NAME", "CAMPAIGN_STATUS", "CAMPAIGN_OBJECTIVE", "AD_SET_NAME", "AD_SET_STATUS", "AD_SET_BUDGET", "AD_SET_COST_MODEL", "AD_NAME"
  • metrics
    array of strings
    Required

    Users can define a set of metrics that they would like populated as columns in the report.

    Example: ["IMPRESSIONS_ON_SPOTIFY","SPEND"]
    Allowed values: "AD_COMPLETES", "AVG_STREAMS_PER_LISTENER", "AVG_STREAMS_PER_NEW_LISTENER", "CLICKS", "COMPLETION_RATE", "CPCL", "CPM", "CTR", "FREQUENCY", "FREQUENCY_OF_AD_COMPLETES", "IMPRESSIONS_OFF_SPOTIFY", "IMPRESSIONS_ON_SPOTIFY", "INTENT_RATE", "LISTENERS", "LISTENER_CONVERSION_RATE", "NEW_LISTENERS", "NEW_LISTENER_CONVERSION_RATE", "PLAYED_TO_100", "PLAYED_TO_25", "PLAYED_TO_50", "PLAYED_TO_75", "REACH", "REACH_OF_AD_COMPLETES", "SPEND", "STARTS", "STREAMS", "UNMUTES", "MODELED_ADD_TO_CART", "MODELED_LEADS", "MODELED_PAGE_VIEWS", "MODELED_PURCHASES", "UNMODELED_ADD_TO_CART", "UNMODELED_LEADS", "UNMODELED_PAGE_VIEWS", "UNMODELED_PURCHASES", "VIDEO_VIEWS", "VIDEO_EXPANDS", "VIDEO_EXPAND_RATE", "SKAD_APP_INSTALLS", "KOCHAVA_APP_INSTALLS", "APPSFLYER_APP_INSTALLS"
  • statuses
    array of strings

    Users can define a set of statuses that will be used to filter the primary entity displayed in the report. Not every status is valid for each entity type. The valid statuses for each entity are the following: Ad: APPROVED, ARCHIVED, PENDING, PENDING_APPROVAL, REJECTED Ad Set: ACTIVE, APPROVED, ARCHIVED, COMPLETED, PENDING_APPROVAL, READY, REJECTED Campaign: ACTIVE, APPROVED, ARCHIVED, COMPLETED, PENDING_APPROVAL, READY, REJECTED, PAUSED

    Note: The status for the Campaign entity type is not its direct status but is derived from its Ad Sets' statuses.

    Example: ["ACTIVE","COMPLETED"]
    Allowed values: "ACTIVE", "COMPLETED", "STOPPED", "PAUSED", "PENDING_APPROVAL", "REJECTED"
  • campaign_ids
    array of strings

    A list of Campaign IDs to include in the report. Leaving this field empty means the user wants a report of all campaigns. This filter will be ignored if the primary entity is the Ad Account.

    Example: []

    A unique identifier for the entity.

    Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
  • report_start
    string [date-time]

    The report time range start time. This field is required if the granularity is DAY.

    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). 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).

    When specifying the time range for reports, please adhere to the following guidelines based on the selected granularity.

    • LIFETIME: For lifetime reports, the time component will be truncated to zero. For example, 2021-01-23T22:15:15Z -> 2021-01-23T00:00:00Z. The start and end date (if specified) must also be within 365 days of each other.
    • DAY: The start and end date must be within 365 days of each other. In addition, UTC midnight timestamps must be used (no hours, minutes, or seconds).
    Example: "2024-01-23T00:00:00Z"
  • report_end
    string [date-time]

    The report time range end time. This field is required if the granularity is DAY.

    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). 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).

    When specifying the time range for reports, please adhere to the following guidelines based on the selected granularity.

    • LIFETIME: For lifetime reports, the time component will be truncated to zero. For example, 2021-01-23T22:15:15Z -> 2021-01-23T00:00:00Z. The start and end date (if specified) must also be within 365 days of each other.
    • DAY: The start and end date must be within 365 days of each other. In addition, UTC midnight timestamps must be used (no hours, minutes, or seconds).
    Example: "2024-02-23T00:00:00Z"

Response

Response containing the CSV report ID.

The response will contain the ID of the created report. This ID can be used as a path parameter to retrieve the report status and result via the Get Async Report endpoint.

  • id
    string [uuid]

    A unique identifier for the entity.

    Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"

Response sample