---
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`

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.

---

[API](https://skmtc.net/pinterest/apis/pinterest-rest-api.md) · [All operations](https://skmtc.net/pinterest/apis/pinterest-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pinterest/pinterest-rest-api/revisions/b698c180678a/schema)