Create an asynchronous report to view specific metrics and dimensions associated with your ad campaign. A report can access the past 13 months of data and has an 8 hour data latency, which means that if an impression was delivered at least 8 hours before the report was run, it's reflected in the report. The current attribution window is 14 days which means attributions come in up to 14 days after the impression and are reported based on the time of conversion, not the time of impression. If you want to get fast, lightweight data for dashboards and real-time campaign optimization, see About synchronous metrics.

When to use synchronous metrics vs. asynchronous reports

Use case	Recommended endpoint	Why
Real-time campaign optimization. Check today's metrics and adjust active campaigns.	Synchronous metrics	Sub-3-second response; no job queue wait.
Dashboard UI data refresh	Synchronous metrics	Fast enough for interactive experiences; supports day-level granularity.
Regularly scheduled background syncs (e.g. nightly pipeline pulling last 7 days)	Synchronous metrics or asynchronous reports	You can use either approach but synchronous metrics should be used for a time range of ≤ 7 days with no segmentation.
Historical data backfill for a new account (months of data)	Asynchronous reports	Synchronous metrics are capped at 7 days so large pulls of data must be done asynchronously.
Segmented reports (by placement, geo, audience)	Asynchronous reports	Asynchronous reports supports segmentation parameters needed for this volume of data, synchronous metrics doesn't.
CSV export	Asynchronous reports	Results are written to a downloadable file, which isn't suited for synchronous metrics.

Key characteristics at a glance

Attribute	Synchronous metrics	Asynchronous reports
Max time range	7 days	13 months
Supported granularity	Day, Total	Day, Total, Hour
Segmentation	Not supported	Supported (geo, etc.)
Data retention	37 months	37 months
Query response SLA	< 3 seconds	~ 1 hour

Create an asynchronous report

To create an asynchronous report make a POST Create asynchronous reports call and include the following in your request body parameters:

name - the name of the report
description - An optional description of the report.
metrics - Any metrics you want the report to include. Must have at least one. For multiple metrics, use a comma-delimited list.
dimensions - Any dimensions you want the report to include. For multiple dimensions, use a comma-delimited list.
filters - Any filters you want applied to the report. For multiple filters, use a comma-delimited list.
A start_at and an end_at date and time in ISO 8601 format (e.g. 2025-08-01T00:00:00Z). Set the timezones to align with your ad account timezone to ensure the data aligns with the Ads Manager UI.

A successful call returns your created report, or a list of your created reports if you created multiple with the call. In order to view the details of these reports, make a GET Get a report call and download the report from the pre-signed URL delivered in the response.

Specify a delivery address for the report to be sent to

If you want your report sent directly to a specified delivery_address, also include the following in your request body parameters:

Specify delivery_type to upload.
Specify your delivery_address. It must be a publicly accessible HTTPS endpoint that accepts PUT requests with a CSV payload.

For example, a backend endpoint that accepts PUT requests and writes the body to storage, or a pre-signed object storage URL that accepts PUT requests.

A successful call with these parameters sends an HTTP PUT request to the delivery_address which includes the header Content-Type: text/csv, and sends the report file as the raw request body.

📘
If your endpoint is behind infrastructure such as Cloudflare or NGINX and returns a 307 or 308 redirect, delivery of the report could fail depending on redirect handling. We're working to address this known issue.

Get a report

Use the GET Get a report call to get details of an asynchronous report specified by its unique identifier, including the report's status, metrics, dimensions, filters, and a download URL to access the report CSV file.

Metrics

Metrics are quantitative measurements, representing numerical data, calculations, and performance indicators. The table below lists the metrics that can asynchronous report can contain.

Name	Description
actions	Attributed actions. This represents the number of times that someone exposed to your ad has completed an action, tracked by the Roku Pixel or Conversions API. A column is only displayed for an event if it has one or more attributed action. You need to pass `activity_name` as a dimension, in addition to `actions` as a metric, if you want your report to include this metric.
cpa	Cost per action. The amount you pay per your campaign's goal action, calculated by dividing spend into those actions. CPA does not include non-goal actions. A campaign with Page View goal that also has Sign-up and Purchase events would calculate the CPA like this: CPA = Spend / Page Views. You need to pass `activity_name` as a dimension, in addition to `cpa` as a metric, if you want your report to include this metric.
cpcv	Cost per completed view. The amount you pay every time your ad is viewed to completion, calculated by dividing spend by video completions.
cpm	Cost per mille/thousand. The effective cost you pay for 1,000 impressions delivered.
cpur	Cost per unique reach. The amount you pay to reach a unique household, calculated by dividing spend by unique households reached.
roas	Return on ad spend. A ratio comparing how much you spent on ads and how much purchase value they drove, calculated by dividing total purchase value by total ad spend. This is only reportable when a purchase pixel is applied with transaction values passed.
household_frequency	The average number of times a unique household has seen your ad. A household frequency of 3 means that on average, your ad was viewed 3 times within the same household.
household_reach	The total number of unique households who saw your ad.
impressions	An impression is equal to your ad being shown once.
order_value	The total revenue attributed to your ads. Calculated by the sum of the `order_value` for all attributed conversions in each group of dimensions. This is aggregated per report row, not per individual order. You need to pass `activity_name` as a dimension, in addition to `order_value` as a metric, if you want your report to include this metric.
spend	The total amount paid for your ads.
total_unique_actions	The number of times a unique household exposed to your ad has completed an action on your site, tracked by the Roku Pixel. These are attributed actions. You need to pass `activity_name` as a dimension, in addition to `total_unique_actions` as a metric, if you want your report to include this metric.
vcr	Video completion rate. The percent of videos watched all the way through. Calculated by dividing video completions by impressions.
video_view_25pct	The number of times your ad was viewed to 25% completion.
video_view_50pct	The number of times your ad was viewed to 50% completion.
video_view_75pct	The number of times your ad was viewed to 75% completion.
video_view_100pct	The number of times your ad was viewed to 100% completion.

Dimensions

Qualitative attributes used to describe, categorize, and group data. The table below lists the dimensions that can asynchronous report can contain.

Name	Description
activity_name	You need to pass `activity_name` as a dimension if you want to collect any of the following attribution related metrics: `actions`, `total_unique_actions`, `order_value`, and `CPA`.
account_name	The name of the account
account_id	The identifier of the account
campaign_id	The identifier of the campaign
ad_group_budget	The budget set for the ad group
ad_group_end_time	The end time set for the ad group
campaign_name	The name of the campaign
ad_group_start_time	The start time set for the ad group
country	Name of country that the ad is delivered in
creative_id	The identifier of the creative
creative_name	The name of the creative
date	Represents a single date in the report. Displayed as `MM/DD/YYYY`
metro_market	Metropolitan market, or Designated Market Area (DMA) in the U.S. The geographic area centered around a major city, including the city and its surrounding suburbs and nearby towns, that’s considered one unified advertising audience.
month	Month of the year
placement	Where your ad is served; on the Roku platform or in specific streaming apps, for example. See Help Center article on Placements.
postal_code	International postal code for the given household at the time the ad is served to that household.
state_territory	The territory or US state in which the ad is run.
week	Week of the year, for example: 1/26/26
year	Year, for example: 2026
hour	Hour of day: 1-24

Filters

Filters define and limit data retrieved and tell your report to display only the relevant, specific information you specify.

Name	Description
campaign_uid	The unique identifier of a campaign
account_uid	The unique identifier of an account

Event names

List of possible event_names that could be returned in your report:

achieve_level
add_payment_info
add_to_cart
add_to_wishlist
app_install
complete_registration
contact
customize_product
donate
download
find_location
first_view_video
initiate_checkout
lead
page_view
purchase
qss
schedule
search
session_start
sign_up
start_trial
subscribe
subscription_cancellation
subscription_renewal
unlock_achievement
view_content