PIpinterest
ad_accounts

Create async request for an account analytics report

Changed on

This returns a token that you can use to download the report when it is ready. Note that this endpoint requires the parameters to be passed as JSON-formatted in the request body. This endpoint does not support URL query parameters.

  • The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.
  • If granularity is not HOUR, you can pull data from up to 914 days before the current date in UTC time, with a maximum time range of 186 days.
  • If granularity is HOUR, you can pull data from up to 8 days before the current date in UTC time, with a maximum time range of 3 days.
  • If level is PRODUCT_ITEM, you can pull data from up to 92 days before the current date in UTC time, with a maximum time range of 31 days.
  • If level is PRODUCT_ITEM, ad_ids and ad_statuses parameters are not allowed. Any columns related to pin promotion and ad is not allowed either.
post/ad_accounts/{ad_account_id}/reports

Request

Path parameters

ad_account_idstring required

Unique identifier of an ad account.

Request body

ad_group_idsPinterestLibIntegerFormatType[]

List of ad group ids

ad_group_statusesAdGroupSummaryStatus[]

List of values for filtering

ad_idsPinterestLibIntegerFormatType[]

List of ad ids. This parameter is not supported for Product Item level reports.

ad_statusesPinPromotionSummaryStatus[]

List of values for filtering. This parameter is not supported for Product Item level reports.

attribution_typesConversionReportAttributionType[]

List of attribution types for the conversion report.

campaign_brand_labelstring

Campaign brand label for filtering.

campaign_custom_labelstring

Campaign custom label for filtering.

campaign_idsPinterestLibIntegerFormatType[]

List of campaign ids

campaign_statusesCampaignSummaryStatus[]

List of status values for filtering

click_window_days0 | 1 | 7 | 14 | 30 | 60
columnsReportingColumnAsync[]

Metric and entity columns. Pin promotion and ad related columns are not supported for Product Item level reports.

combine_targeting_typesboolean

Determines if the targeting types included in the request should be consolidated into a single breakdown.

conversion_report_time'TIME_OF_AD_ACTION' | 'TIME_OF_CONVERSION'

Conversion report time type

end_datestring required

Metric report end date (UTC). Format: YYYY-MM-DD

end_hourinteger

Which hour of the end date to stop the report (inclusive). Only allowed for hourly reports.

engagement_window_days0 | 1 | 7 | 14 | 30 | 60
granularity'TOTAL' | 'DAY' | 'HOUR' | 'WEEK' | 'MONTH' required

Specifies the time interval at which analytics data is broken down. Determines how metrics are grouped within the requested date range. Note: The HOUR enum no longer provides data for conversion metrics, but it still returns data for non-conversion metrics. All other enums are unchanged.

level'ADVERTISER' | 'ADVERTISER_TARGETING' | 'CAMPAIGN' | 'CAMPAIGN_TARGETING' | 'AD_GROUP' | 'AD_GROUP_TARGETING' | 'PIN_PROMOTION' | 'PIN_PROMOTION_TARGETING' | 'KEYWORD' | 'PRODUCT_GROUP' | 'PRODUCT_GROUP_TARGETING' | 'PRODUCT_ITEM' | 'PRODUCT_ITEM_TARGETING'

Level of the reporting request

primary_sort'BY_ID' | 'BY_DATE'

Whether to first sort the report by date or by ID

product_group_idsPinterestLibIntegerFormatType[]

List of product group ids

product_group_statusesProductGroupSummaryStatus[]

List of values for filtering

product_item_idsPinterestLibIntegerFormatType[]

List of product item ids

report_format'JSON' | 'CSV'

Format of generated report

reporting_timezone'PINTEREST_TIME_ZONE' | 'AD_ACCOUNT_TIME_ZONE'

Specify the timezone to be applied for the reporting.

start_datestring required

Metric report start date (UTC). Format: YYYY-MM-DD

start_hourinteger

Which hour of the start date to begin the report. Only allowed for hourly reports.

targeting_typesAdAdsAnalyticsAsyncTargetingTypes[]

List of targeting types. Requires level to be a value ending in _TARGETING.

view_window_days0 | 1 | 7 | 14 | 30 | 60

Example request

{
  "ad_group_statuses": [
    "RUNNING"
  ],
  "ad_statuses": [
    "APPROVED"
  ],
  "attribution_types": [
    "INDIVIDUAL"
  ],
  "columns": [
    "SPEND_IN_MICRO_DOLLAR"
  ],
  "conversion_report_time": "TIME_OF_AD_ACTION",
  "level": "CAMPAIGN",
  "metrics_filters": [
    {
      "field": "SPEND_IN_DOLLAR",
      "operator": "LESS_THAN"
    }
  ],
  "product_group_statuses": [
    "RUNNING"
  ],
  "report_format": "JSON",
  "reporting_timezone": "PINTEREST_TIME_ZONE"
}

Response

The request has succeeded.

messagestring nullable
report_status'DOES_NOT_EXIST' | 'FINISHED' | 'IN_PROGRESS' | 'EXPIRED' | 'FAILED' | 'CANCELLED'

Possible status for a bulk reporting job

tokenstring

Example response

{
  "report_status": "FINISHED"
}

Changes

  • v5b698c180678aRevision changes
    • breaking

      added the new required request property

    • breaking

      added the new required request property

    • breaking

      added the new required request property

    • warning

      removed subschema #1 subschema #2 subschema #3 from the request body allOf list

    • warning

      added the new CANCELLED enum value to the response property for the response status

    • warning

      added the new DOES_NOT_EXIST enum value to the response property for the response status

    • warning

      added the new EXPIRED enum value to the response property for the response status

    • warning

      added the new FAILED enum value to the response property for the response status

    • warning

      added the new FINISHED enum value to the response property for the response status

    • warning

      added the new IN_PROGRESS enum value to the response property for the response status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      removed from the response property allOf list for the response status

  • v5537bde5a50b1Revision changes
    • breaking

      added subschema #1 subschema #3 to the request body allOf list

    • warning

      removed subschema #1 subschema #3 from the request body allOf list