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.
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 reportdescription- optional description of the reportmetrics- 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_atand anend_atdate 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.
If you want your report sent directly to a specified delivery_address, also include the following in your request body parameters:
- Specify
delivery_typetoupload. - 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.
Get a report
Use the GETGet 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 |
| 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 You need to pass |
| 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 |
| 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 |
| campaign_name | The name of the campaign |
| ad_group_id | The identifier of the ad group |
| ad_group_budget | The budget set for the ad group |
| ad_group_end_time | The end time set for the ad group |
| 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 |
| year | Year |
| hour | Hour of day |
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