--- title: "Create async request for an account analytics report" method: POST path: "/ad_accounts/{ad_account_id}/reports" tags: ["ad_accounts"] --- # Create async request for an account analytics report `POST /ad_accounts/{ad_account_id}/reports` ## Request - Base URL: `https://api.pinterest.com/v5` - URL: `https://api.pinterest.com/v5/ad_accounts/{ad_account_id}/reports` - Auth: OAuth 2 - Authorization code: `https://www.pinterest.com/oauth/` - Token URL: `https://api.pinterest.com/v5/oauth/token` scopes: `ads:read` - TypeScript: (a function with typed inputs; its response is checked against the schema) 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](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): 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. ## Path parameters - `ad_account_id` string, required ## Request body - AdsAnalyticsCreateAsyncRequest - `ad_group_ids` PinterestLibIntegerFormatType[]: List of ad group ids - `ad_group_statuses` AdGroupSummaryStatus[]: List of values for filtering - `ad_ids` PinterestLibIntegerFormatType[]: List of ad ids. This parameter is not supported for Product Item level reports. - `ad_statuses` PinPromotionSummaryStatus[]: List of values for filtering. This parameter is not supported for Product Item level reports. - `attribution_types` ConversionReportAttributionType[]: List of attribution types for the conversion report. - `campaign_brand_label` string: Campaign brand label for filtering. - `campaign_custom_label` string: Campaign custom label for filtering. - `campaign_ids` PinterestLibIntegerFormatType[]: List of campaign ids - `campaign_objective_types` unknown[]: List of values for filtering. ["WEB_SESSIONS"] is in BETA. - unknown - `campaign_statuses` CampaignSummaryStatus[]: List of status values for filtering - `click_window_days` 0 | 1 | 7 | 14 | 30 | 60 - `columns` ReportingColumnAsync[]: Metric and entity columns. Pin promotion and ad related columns are not supported for Product Item level reports. - `combine_targeting_types` boolean: 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 - `custom_conversion_event_metrics` CustomConversionEventMetrics[]: List of advertiser-defined custom conversion event metrics to include in the report - `custom_event_metrics_type` 'ADE_COST_PER_ACTION' | 'ADE_ROAS' | 'ADE_TOTAL_CONVERSIONS' | 'ADE_TOTAL_VALUE_IN_MICRO_DOLLAR' | 'ADE_AVERAGE_VALUE_IN_MICRO_DOLLAR' | 'ADE_TOTAL_CLICK' | 'ADE_TOTAL_CLICK_VALUE_IN_MICRO_DOLLAR' | 'ADE_TOTAL_VIEW' | 'ADE_TOTAL_VIEW_VALUE_IN_MICRO_DOLLAR' | 'ADE_TOTAL_CONVERSION_RATE' | 'ADE_WEB_COST_PER_ACTION' | 'ADE_WEB_ROAS' | 'ADE_TOTAL_WEB_CONVERSIONS' | 'ADE_TOTAL_WEB_VALUE_IN_MICRO_DOLLAR' | 'ADE_TOTAL_WEB_CLICK' | 'ADE_TOTAL_WEB_CLICK_VALUE_IN_MICRO_DOLLAR' | 'ADE_TOTAL_WEB_VIEW' | 'ADE_TOTAL_WEB_VIEW_VALUE_IN_MICRO_DOLLAR' | 'ADE_INAPP_COST_PER_ACTION' | 'ADE_INAPP_ROAS' | 'ADE_TOTAL_INAPP_CONVERSIONS' | 'ADE_TOTAL_INAPP_VALUE_IN_MICRO_DOLLAR' | 'ADE_TOTAL_INAPP_CLICK' | 'ADE_TOTAL_INAPP_CLICK_VALUE_IN_MICRO_DOLLAR' | 'ADE_TOTAL_INAPP_VIEW' | 'ADE_TOTAL_INAPP_VIEW_VALUE_IN_MICRO_DOLLAR' | 'ADE_OFFLINE_COST_PER_ACTION' | 'ADE_OFFLINE_ROAS' | 'ADE_TOTAL_OFFLINE_CONVERSIONS' | 'ADE_TOTAL_OFFLINE_VALUE_IN_MICRO_DOLLAR' | 'ADE_TOTAL_OFFLINE_CLICK' | 'ADE_TOTAL_OFFLINE_CLICK_VALUE_IN_MICRO_DOLLAR' | 'ADE_TOTAL_OFFLINE_VIEW' | 'ADE_TOTAL_OFFLINE_VIEW_VALUE_IN_MICRO_DOLLAR' | 'ADE_TOTAL_CONVERSION_PRODUCT_QUANTITY' | 'ADE_TOTAL_CONVERSION_PRODUCT_VALUE' | 'ADE_TOTAL_CONVERSION_PRODUCT_VALUE_IN_MICRO_UNITS' | 'ADE_TOTAL_CONVERSION_PRODUCT_VALUE_IN_USD' | 'ADE_TOTAL_CONVERSION_PRODUCT_VALUE_IN_MICRO_USD' | 'ADE_TOTAL_WEB_CONVERSION_PRODUCT_QUANTITY' | 'ADE_TOTAL_WEB_CONVERSION_PRODUCT_VALUE' | 'ADE_TOTAL_WEB_CONVERSION_PRODUCT_VALUE_IN_MICRO_UNITS' | 'ADE_TOTAL_WEB_CONVERSION_PRODUCT_VALUE_IN_USD' | 'ADE_TOTAL_WEB_CONVERSION_PRODUCT_VALUE_IN_MICRO_USD' | 'ADE_TOTAL_INAPP_CONVERSION_PRODUCT_QUANTITY' | 'ADE_TOTAL_INAPP_CONVERSION_PRODUCT_VALUE' | 'ADE_TOTAL_INAPP_CONVERSION_PRODUCT_VALUE_IN_MICRO_UNITS' | 'ADE_TOTAL_INAPP_CONVERSION_PRODUCT_VALUE_IN_USD' | 'ADE_TOTAL_INAPP_CONVERSION_PRODUCT_VALUE_IN_MICRO_USD' | 'ADE_TOTAL_OFFLINE_CONVERSION_PRODUCT_QUANTITY' | 'ADE_TOTAL_OFFLINE_CONVERSION_PRODUCT_VALUE' | 'ADE_TOTAL_OFFLINE_CONVERSION_PRODUCT_VALUE_IN_MICRO_UNITS' | 'ADE_TOTAL_OFFLINE_CONVERSION_PRODUCT_VALUE_IN_USD' | 'ADE_TOTAL_OFFLINE_CONVERSION_PRODUCT_VALUE_IN_MICRO_USD', required: Metrics for custom defined conversion event. - `custom_event_name` string, required: Name of the advertiser-defined custom conversion event - `end_date` string, required: Metric report end date (UTC). Format: YYYY-MM-DD - `end_hour` integer: Which hour of the end date to stop the report (inclusive). Only allowed for hourly reports. - `engagement_window_days` 0 | 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 - `metrics_filters` AdsAnalyticsMetricsFilter[]: List of metrics filters - `field` 'SPEND_IN_DOLLAR' | 'TOTAL_IMPRESSION', required: Reporting columns for sync reporting data filter - `operator` 'LESS_THAN' | 'GREATER_THAN', required: Filter operator for sync reporting - `values` number[], required: List of values for filtering - `primary_sort` 'BY_ID' | 'BY_DATE': Whether to first sort the report by date or by ID - `product_group_ids` PinterestLibIntegerFormatType[]: List of product group ids - `product_group_statuses` ProductGroupSummaryStatus[]: List of values for filtering - `product_item_ids` PinterestLibIntegerFormatType[]: 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_date` string, required: Metric report start date (UTC). Format: YYYY-MM-DD - `start_hour` integer: Which hour of the start date to begin the report. Only allowed for hourly reports. - `targeting_types` AdAdsAnalyticsAsyncTargetingTypes[]: List of targeting types. Requires `level` to be a value ending in `_TARGETING`. - `view_window_days` 0 | 1 | 7 | 14 | 30 | 60 ## Response `200` The request has succeeded. - AdsAnalyticsCreateAsyncResponse - `message` string, nullable - `report_status` 'DOES_NOT_EXIST' | 'FINISHED' | 'IN_PROGRESS' | 'EXPIRED' | 'FAILED' | 'CANCELLED': Possible status for a bulk reporting job - `token` string ## Other responses - `400`: The request could not be understood by the server due to unexpected data. - `401`: Authentication is required and has either failed or not been provided. - `403`: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. - `404`: The requested resource could not be found on this server. - `429`: The user has sent too many requests in a given amount of time and is being rate limited. - `default`: An unexpected error response. ## Changes - **2026-06-04** (v5) `b698c180678a`: 3 breaking, 7 warning, 33 info - added the new required request property `end_date` - added the new required request property `granularity` - added the new required request property `start_date` - removed `subschema #1, subschema #2, subschema #3` from the request body `allOf` list - …39 more - **2025-12-11** (v5) `537bde5a50b1`: 1 breaking, 1 warning - added `subschema #1, subschema #3` to the request body `allOf` list - removed `subschema #1, subschema #3` from the request body `allOf` list - **2025-12-11** (v5) `79f62f71f05b`: 3 info - added the new `PRODUCT_ITEM_CURRENCY` enum value to the request property `allOf[subschema #3]/columns/items/` - added the new `TOTAL_APP_INSTALL_CONVERSION_RATE` enum value to the request property `allOf[subschema #3]/columns/items/` - added the new `TOTAL_INAPP_APP_INSTALL_CONVERSION_RATE` enum value to the request property `allOf[subschema #3]/columns/items/` - **2025-10-16** (v5) `14c297539b64`: 7 info - added the new optional request property `allOf[subschema #3]/custom_conversion_event_metrics` - added the new `CAMPAIGN_CUSTOM_LABELS` enum value to the request property `allOf[subschema #3]/columns/items/` - added the new `TOTAL_ADD_TO_WISHLIST` enum value to the request property `allOf[subschema #3]/columns/items/` - added the new `TOTAL_SUBSCRIBE` enum value to the request property `allOf[subschema #3]/columns/items/` - …3 more - …earlier changes not shown [Operation history](https://skmtc.dev/pinterest/apis/pinterest-rest-api/changes/ad_accounts/:ad_account_id/reports/post.md) --- [API](https://skmtc.dev/pinterest/apis/pinterest-rest-api.md) - [All operations](https://skmtc.dev/pinterest/apis/pinterest-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pinterest/apis/pinterest-rest-api/revisions/b698c180678a?raw)