# Measurement

Measurement endpoints provides stats data that is updated approximately every 15 minutes.

All stats requests can be made with *TOTAL*, *DAY*, or *HOUR* **granularity**.

## Request/Response Pattern[​**](#requestresponse-pattern "Copy to clipboard")

Stats endpoints have a consistent request and response pattern.

### Request Pattern[​**](#request-pattern "Copy to clipboard")

**Pattern:**

GET /v1/{PLURAL\_ENTITY\_NAME}/{ENTITY\_ID}/stats

**Example:**

GET /v1/campaigns/ff869d1f-0923-4d28-8577-4c36291f0fca/stats

### Response Pattern - TOTAL Granularity[​**](#response-pattern---total-granularity "Copy to clipboard")

> Response pattern for TOTAL Granularity requests

```
{
  "request_status": "success",
  "request_id": "57ad1ad600076e58fa35e192",
  "total_stats": [
    {
      "sub_request_status": "success",
      "total_stat": {
        "id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
        "type": "CAMPAIGN",
        "granularity": "TOTAL",
        "stats": {
          "impressions": 0,
          "swipes": 0,
          "spend": 0,
          "quartile_1": 0,
          "quartile_2": 0,
          "quartile_3": 0,
          "view_completion": 0,
          "screen_time_millis": 0
        }
      }
    }
  ]
}
```

### Response Pattern - DAY Granularity[​**](#response-pattern---day-granularity "Copy to clipboard")

> Response pattern for DAY Granularity requests

```
{
  "request_status": "success",
  "request_id": "57ad240f000756e8d435a6cd",
  "timeseries_stats": [
    {
      "sub_request_status": "success",
      "timeseries_stat": {
        "id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
        "type": "CAMPAIGN",
        "granularity": "DAY",
        "start_time": "2016-08-05T22:00:00.000-07:00",
        "end_time": "2016-08-07T22:00:00.000-07:00",
        "timeseries": [
          {
            "start_time": "2016-08-05T22:00:00.000-07:00",
            "end_time": "2016-08-06T22:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          },
          {
            "start_time": "2016-08-06T22:00:00.000-07:00",
            "end_time": "2016-08-07T22:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          }
        ]
      }
    }
  ]
}
```

Show more▼

### Response Pattern - HOUR Granularity[​**](#response-pattern---hour-granularity "Copy to clipboard")

> Response pattern for HOUR Granularity requests

```
{
  "request_status": "success",
  "request_id": "57ad245a000e3c88bc33ea4e",
  "timeseries_stats": [
    {
      "sub_request_status": "success",
      "timeseries_stat": {
        "id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
        "type": "CAMPAIGN",
        "granularity": "HOUR",
        "start_time": "2016-08-05T18:00:00.000-07:00",
        "end_time": "2016-08-06T18:00:00.000-07:00",
        "timeseries": [
          {
            "start_time": "2016-08-05T18:00:00.000-07:00",
            "end_time": "2016-08-05T19:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          },
          {
            "start_time": "2016-08-05T19:00:00.000-07:00",
            "end_time": "2016-08-05T20:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          }
          ....
          {
            "start_time": "2016-08-06T16:00:00.000-07:00",
            "end_time": "2016-08-06T17:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          },
          {
            "start_time": "2016-08-06T17:00:00.000-07:00",
            "end_time": "2016-08-06T18:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          }
        ]
      }
    }
  ]
}
```

Show more▼

### Request Parameters[​**](#request-parameters "Copy to clipboard")

| Attribute                      | Description                                                                                                                                                                  | Required | Possible Values                                                                                                             |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| breakdown                      | Object-level breakdown                                                                                                                                                       | O        | ad, adsquad \[Only available on Campaign Stats endpoint], campaign \[Only available on Ad Account Stats endpoint]           |
| async                          | Designates processing of report to be asynchronous                                                                                                                           | O        | true                                                                                                                        |
| async\_format                  | Designates the response format of asynchronous reporting, can be either a csv or excel file                                                                                  | O        | csv, excel                                                                                                                  |
| fields                         | Metrics requested (comma-separated)                                                                                                                                          | O        | (see table below; default: impressions,spend)                                                                               |
| end\_time                      | End Time (ISO 8601)                                                                                                                                                          | R\*      |                                                                                                                             |
| start\_time                    | Start Time (ISO 8601)                                                                                                                                                        | R\*      |                                                                                                                             |
| granularity                    | Metrics granularity                                                                                                                                                          | R        | TOTAL, DAY, HOUR, LIFETIME                                                                                                  |
| test                           | Return Sample (fake) Stats                                                                                                                                                   | O        | false (default), true                                                                                                       |
| dimension                      | Insight-level breakdown                                                                                                                                                      | O        | GEO, DEMO, INTEREST, DEVICE                                                                                                 |
| pivot                          | The pivot to be used for insights breakdown                                                                                                                                  | O        | country, region, dma, gender, age\_bucket, interest\_category\_id, interest\_category\_name, operating\_system, make, model |
| action\_report\_time           | Specifies the principle for conversion reporting                                                                                                                             | O        | conversion (default), impression\*\*                                                                                        |
| swipe\_up\_attribution\_window | Attribution window for swipe ups                                                                                                                                             | O        | 1\_DAY, 7\_DAY, 28\_DAY (default)                                                                                           |
| view\_attribution\_window      | Attribution window for views                                                                                                                                                 | O        | none, 1\_HOUR, 3\_HOUR, 6\_HOUR, 1\_DAY (default), 7\_DAY, 28\_DAY\*\*\*                                                    |
| position\_stats                | Position metric breakdown for Snap Ads within a Story Ad                                                                                                                     | O        | true                                                                                                                        |
| omit\_empty                    | Omits records with zero data for all metrics for a given date/entity. If there is data for any metric for a given date/entity, all metrics for that date/entity are returned | O        | false (default), true                                                                                                       |
| conversion\_source\_types      | Conversion source breakout by platform                                                                                                                                       | O        | web, app, offline\*\*, total, total\_off\_platform, total\_on\_platform                                                     |
| limit                          | The limit parameter specifies how many entities should be returned per page                                                                                                  | O        | integer, max 200                                                                                                            |

\* start\_time and end\_time are required for DAY and HOUR granularity and they must be set to the start of an hour (e.g. 22:00 not 22:45)<br />\*\* offline conversion data source ( **conversion\_source\_types=offline** ) and impression based conversions<br />\*\* action\_report\_time=impression\*\* ) are available from 1 May 2020 onwards<br />\*\*\* 28\_DAY view\_attribution\_window is deprecated, legacy data is available up until 1 March 2021<br />

## Response Parameters & Finalization[​**](#response-parameters--finalization "Copy to clipboard")

| Attribute                              | Description                                                                                                                                                                                                                                                                                                                                                   |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| finalized\_data\_end\_time             | This attribute defines the time up until when non-conversion reporting metrics are finalized. You can query for all metrics before this time including uniques and reach and they will have the final numbers. For any time after the finalized\_data\_end\_time the metrics are still undergoing de-duplication and finalization and may change accordingly. |
| conversion\_data\_processed\_end\_time | This attribute defines the time up until when conversion metrics are finalized, for any time after the conversion\_data\_processed\_end\_time the conversion metrics are still undergoing processing and may change accordingly. Note that this attribute only covers conversion by time of conversion.                                                       |
| paging                                 | If you are using pagination the `paging` attribute will contain a `next_link` attribute which holds the API call to fetch the next page.                                                                                                                                                                                                                      |

## Pagination[​**](#pagination "Copy to clipboard")

For calls that fetch stats for many entities we recommend that you use pagination. The limit parameter specifies how many entities should be returned per page. The maximum pagination limit is 200.

The returned result will contain a `paging` attribute, this in turn holds a `next_link` attribute which holds the API call to fetch the next page. Paginated calls are rdered by time of creation, non-paginated calls are unsorted.

## Request size limits for large requests[​**](#request-size-limits-for-large-requests "Copy to clipboard")

Synchronous stats responses are size-limited. If the response to a synchronous `GET /v1/{entity}/{id}/stats` request would be too large, the request is rejected with an HTTP `400 Bad Request` and error code `E9001`:

```
{
  "request_status": "ERROR",
  "error_code": "E9001",
  "display_message": "Stats response is too large to process. Reduce the request size by using fewer fields or a shorter date range."
}
```

This is a **client error**, not a transient server error — it will not succeed on retry. To get the data you need, you must reduce the size of the request or move it to [asynchronous reporting](#asynchronous-reporting-requests).

Response size grows with the number of **entities** (breakdown fan-out) × **fields** × **time intervals**. Broad breakdown queries (for example, ad-account or campaign level across many metrics over a multi-day range) are the most likely to exceed the limit.

To stay within the synchronous size limit:

* **For large reports, use [asynchronous reporting](#asynchronous-reporting-requests) (`async=true`).** Async reports return a downloadable CSV or Excel file and are **not** subject to the synchronous response-size limit. This is the recommended path for any large pull.
* Request **fewer `fields`**.
* Use a **shorter date range** and/or a **coarser `granularity`** (`TOTAL` or `DAY` rather than `HOUR`).
* Set **`omit_empty=true`** to drop records that have zero data for all metrics.
* For many-entity breakdowns, [paginate](#pagination) with `limit` ≤ 200 entities per page.

Very large synchronous responses are rejected — there is no fixed byte limit you can rely on. If you hit `E9001`, reduce the request as described above, or switch to asynchronous reporting for large pulls.

## Core Metrics[​**](#core-metrics "Copy to clipboard")

The following metrics are available for all Snap Ads.

| Field Name           | Description                                                                                                                                                       |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| impressions          | Impression Count                                                                                                                                                  |
| swipes               | Swipe-Up Count                                                                                                                                                    |
| view\_time\_millis   | Use screen\_time\_millis instead. Total Time Spent on top Snap Ad (milliseconds)                                                                                  |
| screen\_time\_millis | Total Time Spent on top Snap Ad (milliseconds)                                                                                                                    |
| quartile\_1          | Video Views to 25%                                                                                                                                                |
| quartile\_2          | Video Views to 50%                                                                                                                                                |
| quartile\_3          | Video Views to 75%                                                                                                                                                |
| view\_completion     | Video Views to completion                                                                                                                                         |
| spend                | Amount Spent (micro-currency)                                                                                                                                     |
| coupon\_used\_local  | Amount Spent via Coupon in the assigned currency of Ad Account (micro-currency)                                                                                   |
| coupon\_used\_usd    | Amount Spent via Coupon in USD (micro-currency)                                                                                                                   |
| video\_views         | The total number of impressions that meet the qualifying video view criteria of at least 2 seconds of consecutive watch time or a swipe up action on the Top Snap |

Micro-currency conversion: 1.00 local currency unit = 1000000 Micro-currency. See [Monetary Values](#monetary-values) for details.

IMPORTANT: Metrics are finalized 48 hours after the end of the day in the timezone set by the Ad Account .

## Asynchronous reporting requests[​**](#asynchronous-reporting-requests "Copy to clipboard")

Large reporting requests may time out or return errors, these requests are suitable to be executed using the asynchronous mode. The format of an asynchronous report can be defined either as a comma separated file (CSV) or an Excel spreadsheet. Async reports are not subject to the synchronous [request size limit](#request-size-limits-for-large-requests), so they are the recommended path for large or broad breakdown queries.

Requests marked as asynchronous will produce a `report_run_id` which is needed to check the status of a report, and to retrieve a report, once a report is ready the response body will contain a download url for the finished report. The download url will be valid for seven days, after this the report will be unavailable.

### Generating an async report[​**](#generating-an-async-report "Copy to clipboard")

The first step to generate an asynchronous report is the creation, this request needs to include the `async` parameter.

### HTTP Requests[​**](#http-requests "Copy to clipboard")

`GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats`<br />`GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/stats`<br />`GET https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}/stats`<br />`GET https://adsapi.snapchat.com/v1/ads/{ad_id}/stats`<br />

#### Parameters for creating an asynchronous report[​**](#parameters-for-creating-an-asynchronous-report "Copy to clipboard")

The below listed parameters are specific for asynchronous reporting, aside from these parameters all [request parameters](/marketing-api/Ads-API/measurement.md#request-parameters) are supported, including `granularity` (see the [Request Parameters](#request-parameters) table above for the full set of supported values). The asynchronous creation will return a `report_run_id` which is needed to fetch the report.

Asynchronous requests share the same request parameters as synchronous requests, but do **not** enforce the per-granularity time-window caps that synchronous requests do — for example, the 7-day interval limit on HOUR queries. Async is built for bulk extracts and intentionally allows longer windows. The following still apply to async requests:

* Hour alignment on `start_time` / `end_time` (must fall on the start of an hour), and the earliest queryable date of 2013-01-01.
* When the DAY granularity is used `start_time` and `end_time` are required values, the `start_time` and `end_time` must be the daily boundry for the timezone of the Ad Account in question
* When `start_time` and `end_time` is not defined in combination with granularity TOTAL it is treated the same as granularity LIFETIME

| Parameter     | Description                                                                                 | Required | Possible values      |
| ------------- | ------------------------------------------------------------------------------------------- | -------- | -------------------- |
| async         | Designates processing of report to be asynchronous                                          | R        | true                 |
| async\_format | Designates the response format of asynchronous reporting, can be either a csv or excel file | O        | csv (default), excel |

#### HOUR granularity caveats[​**](#hour-granularity-caveats "Copy to clipboard")

`granularity=HOUR` is supported for asynchronous requests, with the same field and breakdown eligibility rules as synchronous requests:

* **HOUR cannot be combined with Delivery Insights** (`dimension` / `pivot` / `report_dimension`).
* **Not eligible at HOUR:** `conversion_visit*` metrics, and reach/uniques metrics (`uniques`, `frequency`, `total_reach`, `earned_reach`, `attachment_uniques`, `attachment_frequency`). Use `DAY`, `TOTAL`, or `LIFETIME` instead.
* Hourly pulls are up to a 24x row multiplier versus daily — prefer `async_format=csv` over `excel`, which caps near 1,048,576 rows.

#### Example - Step 1 Generating an async report[​**](#example---step-1-generating-an-async-report "Copy to clipboard")

This request produces a `report_run_id` and the `async_status` returned is STARTED.

```
curl "https://adsapi.snapchat.com/v1/adaccounts/ce943c3b-2404-4fff-acb1-259b7b052f27/stats?breakdown=ad&granularity=DAY&view_attribution_window=1_DAY&async=true&omit_empty=true&fields=impressions,total_installs,spend,swipes,attachment_video_views,story_opens,story_completes,shares,saves,conversion_purchases,conversion_purchases_value,conversion_save,conversion_start_checkout,conversion_add_cart,conversion_view_content,conversion_add_billing,conversion_sign_ups,conversion_searches,conversion_level_completes,conversion_app_opens,conversion_page_views&start_time=2024-10-01T00:00:00&end_time=2024-10-08T00:00:00&swipe_up_attribution_window=28_DAY" \
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "SUCCESS",
  "request_id": "acfacd19-bd51-4822-a9d3-e503a523d25f",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:ce943c3b-2404-4fff-acb1-259b7b052f27:1727755200000:7245f6e6-eda4-4650-9255-6e3ab38b95ce",
        "async_status": "STARTED"
      }
    }
  ]
}
```

### Checking the status of an asynchronous report[​**](#checking-the-status-of-an-asynchronous-report "Copy to clipboard")

The second step of asynchronus reporting is checking the status of the report and fetching the download url of the finished report, this request requires the `report_run_id` value returned in the previous request.

### HTTP Requests[​**](#http-requests-1 "Copy to clipboard")

`GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats_report`<br />`GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/stats_report`<br />`GET https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}/stats_report`<br />`GET https://adsapi.snapchat.com/v1/ads/{ad_id}/stats_report`<br />

#### Parameters for checking asynchronous reporting[​**](#parameters-for-checking-asynchronous-reporting "Copy to clipboard")

When checking asynchronous reporting requests the

| Parameter       | Description                        | Required | Possible values |
| --------------- | ---------------------------------- | -------- | --------------- |
| report\_run\_id | The id of the report to be fetched | R        |                 |

#### Example - Step 2 Checking the status of an async report - Report is processing[​**](#example---step-2-checking-the-status-of-an-async-report---report-is-processing "Copy to clipboard")

This request requires the `report_run_id` and the `async_status` returned is RUNNING which indicates that the report is still processing.

```
curl "https://adsapi.snapchat.com/v1/adaccounts/ce943c3b-2404-4fff-acb1-259b7b052f27/stats_report?report_run_id=ASYNC_STATS:6b78bf3c-b7f4-4fcf-b74a-a5aaa91b15ef:1726804800000:7139d12c-910e-4e09-b3fd-a01f82b3af56" \
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "SUCCESS",
  "request_id": "f8a5b7b0-14b4-950c-934f-7b746745e571",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:6b78bf3c-b7f4-4fcf-b74a-a5aaa91b15ef:1726804800000:7139d12c-910e-4e09-b3fd-a01f82b3af56",
        "async_status": "RUNNING"
      }
    }
  ]
}
```

#### Example - Step 2 Checking the status of an async report - Report is completed[​**](#example---step-2-checking-the-status-of-an-async-report---report-is-completed "Copy to clipboard")

This request requires the `report_run_id` and the `async_status` returned is COMPLETED, the url of the report is found in the `result` attribute.

```
curl "https://adsapi.snapchat.com/v1/adaccounts/ce943c3b-2404-4fff-acb1-259b7b052f27/stats_report?report_run_id=ASYNC_STATS:6b78bf3c-b7f4-4fcf-b74a-a5aaa91b15ef:1726804800000:7139d12c-910e-4e09-b3fd-a01f82b3af56" \
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "SUCCESS",
  "request_id": "f8a5b7b0-14b4-950c-934f-7b746745e571",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:6b78bf3c-b7f4-4fcf-b74a-a5aaa91b15ef:1726804800000:7139d12c-910e-4e09-b3fd-a01f82b3af56",
        "async_status": "COMPLETED",
        "result": "https://data-transfer.snapads.com/async-report/snap_ads/ASYNC_STATS:6b78bf3c-b7f4-4fcf-b74a-a5aaa91b15ef:1726804800000:7139d12c-990e-4e09-b3fd-a01f82b3af56/9496dff0-07b9-44d8-8f0b-b44eb276cc9e.xlsx"
      }
    }
  ]
}
```

### Reach Overlap Reporting[​**](#reach-overlap-reporting "Copy to clipboard")

Reach overlap reporting via async reporting is available for Campaigns, Ad Squads and Ads using the Snapchat Marketing API.

Reach values are estimates.

The entities for which the calculation is made must belong to the same Ad Account, overlap reporting across different Ad Accounts is not possible. If an entity has no metrics for the given reporting period (start\_time / end\_time), it will be excluded from the resulting report.

### HTTP Request[​**](#http-request "Copy to clipboard")

`GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats?overlap=true&overlap_type={campaign/ad_squad/ad}&ids={entity1_id,entity_id,...},{entity2_id}&start_time={start_time}&end_time={end_time}&async_format={csv/excel}`<br />

#### Request Parameters[​**](#request-parameters-1 "Copy to clipboard")

| Attribute     | Description                                                                                                                                                  | Possible values                                                          |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| async\_format | Defines the returned format of the report                                                                                                                    | csv,excel                                                                |
| ids           | Two or more Campaign/Ad Squad/Ad entities to calculate the reach overlap for, these have to be the same type of entities and live within the same Ad Account | Comma separated string of up to 100 Campaign ID/Ad Squad ID/Ad ID values |
| overlap       | Indicates whether an overlap calculation should take place                                                                                                   | true                                                                     |
| overlap\_type | Specifies the entity level of the overlap calculation, you cannot use two different types of entities in one report                                          | campaign, ad\_squad, ad                                                  |
| start\_time   | Start time of the report                                                                                                                                     | Start time in ISO format                                                 |
| end\_time     | End time of the report                                                                                                                                       | End time in ISO format                                                   |

#### Example Request[​**](#example-request "Copy to clipboard")

This request generates an async process to create an overlap report in Excel format for two Campaigns in the same Ad Account, for the time period 1-30 April 2024.

```
curl 'https://adsapi.snapchat.com/v1/adaccounts/62f51caa-394c-4f88-905c-71a9859f2b54/stats?overlap=true&overlap_type=campaign&ids=11f5bc01-22a4-469e-ba7e-d4c7edc5ef88%2C50984a9d-1b2e-4d5d-857e-5ac9d3665506%2C54f10e2d-55a8-4924-896d-5a94fba1a0c9&start_time=2024-04-01T07%3A00%3A00.000Z&end_time=2024-04-30T07%3A00%3A00.000Z&async_format=excel' \
-H "Authorization: Bearer meowmeowmeow"
```

#### Response[​**](#response "Copy to clipboard")

```
{
  "request_status": "SUCCESS",
  "request_id": "f5cdc549-f3f3-4aed-9e39-68216ba70be3",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:62f51caa-394c-4f88-905c-71a9859f2b54:1711954800000:f591f1c1-581e-477b-892f-7b8b5365b0e7",
        "async_status": "STARTED"
      }
    }
  ]
}
```

Once the async process for an overlap report is initiated using the above request, follow the steps in [Checking the status of an asynchronous report](/marketing-api/Ads-API/measurement.md#checking-the-status-of-an-asynchronous-report) to check the status and fetch the download url of a completed report.

### Report Format[​**](#report-format "Copy to clipboard")

Below is an example of a `Reach Overlap` report downloaded in excel format. This resulting report includes metrics for `reach` and `uniques`, showing the overlap for the requested entities. The requested entities in this example are two campaigns - Wellness Campaign and Beauty Campaign.

The report starts with `Reached by all`, which is the `Reach Overlap` for all the entities that were included in the report.

#### Example[​**](#example "Copy to clipboard")

* `Row 1` shows the `Reach Overlap` for all the Campaigns in the report.

The report also accounts for the `Total Uniques` for all the entities in the report.

#### Example[​**](#example-1 "Copy to clipboard")

* `Row 2` shows the `Total Uniques` reached by all campaigns in the report.

If `Campaign Id 1` and `Campaign Id 2` are the same, it means the metric is just for that campaign.

#### Example[​**](#example-2 "Copy to clipboard")

* `Row 4` below shows the total `Reach` of the Wellness Campaign
* `Row 6` below shows the total `Uniques` of the Wellness Campaign
* `Row 7` below shows the total `Reach` of the Beauty Campaign
* `Row 9` below shows the total `Uniques` of the Beauty Campaign

If `Campaign Id 1` and `Campaign Id 2` are different it shows an overlap calculation between the two campaigns.

#### Example[​**](#example-3 "Copy to clipboard")

* `Row 5` and `Row 8` shows the `Reach Overlap` of the Wellness Campaign and the Beauty Campaign.

|   | A                                   | B                 | C                                   | D                 | E          | F           |
| - | ----------------------------------- | ----------------- | ----------------------------------- | ----------------- | ---------- | ----------- |
| 1 | Reached by all                      | 6,029             |                                     |                   |            |             |
| 2 | Total Uniques Reached               | 212,351           |                                     |                   |            |             |
| 3 | Campaign Id 1                       | Campaign Name 1   | Campaign Id 2                       | Campaign Name 2   | Reach Type | Reach Value |
| 4 | 11111111-1111-1111-111111111111     | Wellness Campaign | 11111111-1111-1111-111111111111     | Wellness Campaign | Total      | 160.356     |
| 5 | 11111111-1111-1111-111111111111     | Wellness Campaign | 222222222-2222-2222-2222-2222222222 | Beauty Campaign   | Overlap    | 6,029       |
| 6 | 11111111-1111-1111-111111111111     | Wellness Campaign | 11111111-1111-1111-111111111111     | Wellness Campaign | Unique     | 154,327     |
| 7 | 222222222-2222-2222-2222-2222222222 | Beauty Campaign   | 222222222-2222-2222-2222-2222222222 | Beauty Campaign   | Total      | 60,746      |
| 8 | 222222222-2222-2222-2222-2222222222 | Beauty Campaign   | 11111111-1111-1111-111111111111     | Wellness Campaign | Overlap    | 6,029       |
| 9 | 222222222-2222-2222-2222-2222222222 | Beauty Campaign   | 222222222-2222-2222-2222-2222222222 | Beauty Campaign   | Unique     | 54,717      |

## Additional Metrics[​**](#additional-metrics "Copy to clipboard")

See the [Metrics and supported granularities](/marketing-api/Ads-API/measurement.md#metrics-and-supported-granularities) table for a breakdown of the reporting granularities available per Ad type. For LIFETIME granularity the data is only accessible as finalized data, available after 48-72 hours.

| Field Name                            | Snap Ad Types              | Description                                                                                                                                                                                                 |
| ------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| android\_installs                     | APP\_INSTALL               | # of Android App Installs                                                                                                                                                                                   |
| attachment\_avg\_view\_time\_millis   | Any Attachment             | Average Attachment View Time (milli-seconds)                                                                                                                                                                |
| attachment\_frequency                 | Any Attachment             | Average # of Attachment Views per User Reached                                                                                                                                                              |
| attachment\_quartile\_1               | LONGFORM\_VIDEO            | Long Form Video Views to 25%                                                                                                                                                                                |
| attachment\_quartile\_2               | LONGFORM\_VIDEO            | Long Form Video Views to 50%                                                                                                                                                                                |
| attachment\_quartile\_3               | LONGFORM\_VIDEO            | Long Form Video Views to 75%                                                                                                                                                                                |
| attachment\_total\_view\_time\_millis | Any Attachment             | Total Attachment View Time (milli-seconds)                                                                                                                                                                  |
| attachment\_uniques                   | Any Attachment             | # of unique attachment impressions                                                                                                                                                                          |
| attachment\_view\_completion          | LONGFORM\_VIDEO            | Long Form Video Views to completion                                                                                                                                                                         |
| attachment\_video\_views              | LONGFORM\_VIDEO            | Long Form Video Attachment Views, viewed for at least 10 consecutive seconds or reached 97% of the Long Form Video duration                                                                                 |
| avg\_view\_time\_millis               | Any                        | Use avg\_screen\_time\_millis instead. Average Top Snap view time per User Reached                                                                                                                          |
| avg\_screen\_time\_millis             | Any                        | Average Top Snap view time across all impressions                                                                                                                                                           |
| frequency                             | Any                        | Average # of Impressions per User Reached                                                                                                                                                                   |
| ios\_installs                         | APP\_INSTALL               | # of iOS App Installs                                                                                                                                                                                       |
| swipe\_up\_percent                    | Any Attachment             | % of Impressions that Swiped-Up                                                                                                                                                                             |
| total\_installs                       | APP\_INSTALL               | Total # of App Installs                                                                                                                                                                                     |
| uniques                               | Any                        | # of unique impressions                                                                                                                                                                                     |
| video\_views\_time\_based             | Any                        | The total number of impressions that meet the qualifying video view criteria of at least 2 seconds, not including swipe ups                                                                                 |
| video\_views\_5s\*\*                  | Any                        | The total number of impressions that meet the qualifying video view criteria of at least 5 seconds, or a swipe up action on the ad                                                                          |
| video\_views\_15s                     | Any                        | The total number of impressions that meet the qualifying video view criteria of at least 15 seconds, or 97% completion if it's shorter than 15 seconds, or a swipe up action on the ad                      |
| engaged\_views                        | Any                        | The total number of times Snapchatters viewed your video ad for five seconds or longer                                                                                                                      |
| story\_opens                          | STORY                      | # of times users tapped on the ad tile in the feed to view the Story Ad                                                                                                                                     |
| story\_completes                      | STORY                      | # of times users viewed through to the last Snap of your Story Ad                                                                                                                                           |
| landing\_page\_views                  |                            | # of times a Snapchatter has loaded the ad’s landing page after a click page                                                                                                                                |
| profile\_clicks                       | Any                        | # of times users tapped the logo in the upper corner taking them to the profile page                                                                                                                        |
| poll\_sticker\_voted                  | Any with a poll sticker    | Number of votes submitted on a [poll sticker](/marketing-api/Ads-API/stickers.md#poll-sticker). Request this metric in the `fields` query parameter.                                                        |
| position\_impressions                 | STORY                      | # the impression number for this story ad position                                                                                                                                                          |
| position\_screen\_time\_millis        | STORY                      | # the total view time in milliseconds for this story ad position                                                                                                                                            |
| position\_swipe\_up\_percent          | STORY                      | # the swipe up rate for this story ad position                                                                                                                                                              |
| avg\_position\_screen\_time\_millis   | STORY                      | # the average view time for this story ad position                                                                                                                                                          |
| shares                                | LENS, AD\_TO\_LENS, FILTER | # of times lens/filter was shared in a Chat or Story                                                                                                                                                        |
| saves                                 | LENS, AD\_TO\_LENS, FILTER | # of times lens/filter was saved to Memories                                                                                                                                                                |
| paid\_impressions                     | LENS, FILTER, AD\_TO\_LENS | The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter’s viewing session                                      |
| earned\_impressions                   | LENS, FILTER, AD\_TO\_LENS | The number of times your ad was viewed after being shared by a Snapchatter via Chat or Stories                                                                                                              |
| total\_impressions                    | LENS                       | The total number of impressions (Paid and Earned)                                                                                                                                                           |
| play\_time\_millis                    | LENS                       | The total amount of time in where Snapchatters interacted with your Lens in the camera (milliseconds)                                                                                                       |
| total\_reach                          | LENS                       | The estimated number of unique Snapchatters who viewed your Lens ad, either by receiving a Paid or Earned Impression.                                                                                       |
| earned\_reach                         | LENS, FILTER, AD\_TO\_LENS | The estimated number of unique Snapchatters who viewed the filter/lens after being shared by a Snapchatter via Chat or Stories                                                                              |
| native\_leads                         | LEAD\_GENERATION           | Total number of Snapchat users that swipe up, fill out the required fields, and hit ‘Submit’ on Lead Form attachments. If a user swipes down or cancels before hitting 'Submit,' this action is not counted |
| reminders\_set                        | REMINDER                   | Total number of clicks on the CTA when attachment is Reminder                                                                                                                                               |
| place\_opens                          | AD\_TO\_PLACE              | Total number of taps or clicks into the Promoted Place Profile                                                                                                                                              |
| place\_actions                        | AD\_TO\_PLACE              | Total number of actions taken inside the Place Profile, including tapping for directions, calling the business, or viewing the business profile                                                             |

\*engaged\_views are available from 10 February 2025 onwards

\*\*video\_views\_5s are available from 11 March 2025 onwards

Micro-currency conversion: 1.00 local currency unit = 1000000 Micro-currency. See [Monetary Values](#monetary-values) for details.

## Apple Transparent Tracking (ATT) Reporting[​**](#apple-transparent-tracking-att-reporting "Copy to clipboard")

All the users whose activity is tracked using the attribution and measurement services will be split into two categories. Please note that only [conversion metrics](#conversion-event-stats) are affected by the ATT updates.

| User Category               | Description                                                          | User groups in category                                                |
| --------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Fully Tracked group**     | These user groups are fully supported for the features listed below. | Android, iOS opted-in users                                            |
| **Partially tracked group** | These user groups are partially supported.                           | Snap Pixel, iOS opted out users and users reported via Conversions API |

Below is the list of all the reporting fields and API fields that are affected for each group.

| Dimension/Granularity                                                                    | Conversion Sources                                            |                                                                              |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|                                                                                          | **Fully Tracked Group** -<br />Android (in-app), iOS (opt-in) | **Partially tracked Group** -<br />Snap Pixel, iOS (opt-out), Conversion API |
| Time of Conversion<br />action\_report\_time=conversion                                  | Supported                                                     | Supported                                                                    |
| Time of Exposure<br />action\_report\_time=impression                                    | Supported                                                     | Supported                                                                    |
| Event Source<br />(web/app/offline)                                                      | Supported                                                     | Supported                                                                    |
| Entity<br />(campaign/ad set/ad)                                                         | Supported                                                     | Supported                                                                    |
| Age                                                                                      | Supported                                                     | Supported                                                                    |
| Gender                                                                                   | Supported                                                     | Supported                                                                    |
| Age, Gender                                                                              | Supported                                                     | Supported                                                                    |
| Country                                                                                  | Supported                                                     | Supported                                                                    |
| OS                                                                                       | Supported                                                     | Supported                                                                    |
| Platform (on/off snapchat)                                                               | Supported                                                     | Supported                                                                    |
| Region (US Only)                                                                         | Supported                                                     | **NOT Supported**                                                            |
| DMA (US Only)                                                                            | Supported                                                     | **NOT Supported**                                                            |
| Device Make                                                                              | Supported                                                     | **NOT Supported**                                                            |
| SLC (lifestyle category)                                                                 | Supported                                                     | **NOT Supported**                                                            |
| Product                                                                                  | Supported                                                     | **NOT Supported**                                                            |
| Hourly Conversions                                                                       | Supported                                                     | **NOT Supported**                                                            |
| Daily, Total, Lifetime Conversion                                                        | Supported                                                     | Supported                                                                    |
| Swipe Up Window:<br />1\_DAY, 7\_DAY, 28\_DAY<br />View Thru Window:<br />1\_DAY, 7\_DAY | Supported                                                     | Supported                                                                    |
| View Through Window:<br />1\_HOUR, 3\_HOUR, 6\_HOUR                                      | Supported                                                     | Supported                                                                    |
| View Through Window: 28\_DAY\*                                                           | **NOT Supported**                                             | **NOT Supported**                                                            |

Please Note:

* The View Through Window value of 28\_DAY is now effectively deprecated.

* Any legacy data for these users will continue to be returned.

\*This field is now effectively deprecated.

## SKAd Network Reporting[​**](#skad-network-reporting "Copy to clipboard")

Due to the attribution methodology of Apple’s SKAdNetwork there are some limitations when fetching reporting for Ad serving entities that are opted into SKAdNetwork tracking.

* SKAdNetwork conversions reported at the Ad level or below may be modeled based on first party ad engagement signals using statistical methods. Modeling is only applied at the ad level. Please note that you should still take a patient approach to testing and optimization decisions including: waiting 48+ hours before adjusting Bids and Budgets, and starting with high Bids and Budgets to pass privacy thresholds. If you do not, you run the risk of prematurely pausing Ad creatives that may lead to strong performance.

* The available granularities are DAY, TOTAL, and LIFETIME, HOUR granularity is **not** available.

* The conversion window for a SKAd Network SWIPE (click) conversion is 30 day based on the time of conversion, all ad types support SWIPE conversions.

* The conversion window for a SKAd Network VIEW conversion is 24 hours based on the time of conversion. A VIEW is defined as 3 seconds in length.

* The ad types that currently support the VIEW conversion are; SNAP\_AD, LONGFORM\_VIDEO, APP\_INSTALL, REMOTE\_WEBPAGE, DEEP\_LINK, COLLECTION

* Reporting Insights are not available for SKAdNetwork metrics, the use of `report_dimension` is not possible.

## SKAd Network Conversion Metrics[​**](#skad-network-conversion-metrics "Copy to clipboard")

Conversion metrics for the SKAd Network are broken out by Swipe conversions, View conversions, and the total number of conversions.

### SKAd Network Swipe Conversion Metrics[​**](#skad-network-swipe-conversion-metrics "Copy to clipboard")

The following metrics return the SKAd Network SWIPE (click) conversions.

| Name                                               | Description                                                                                                                                                                                     |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| conversion\_total\_installs\_sk\_ad\_network       | Total App Installs tracked via SKAd Network                                                                                                                                                     |
| conversion\_ios\_installs\_sk\_ad\_network         | Exact same metric as conversion\_total\_installs\_sk\_ad\_network                                                                                                                               |
| conversion\_purchases\_sk\_ad\_network             |                                                                                                                                                                                                 |
| conversion\_save\_sk\_ad\_network                  |                                                                                                                                                                                                 |
| conversion\_start\_checkout\_sk\_ad\_network       |                                                                                                                                                                                                 |
| conversion\_add\_cart\_sk\_ad\_network             |                                                                                                                                                                                                 |
| conversion\_view\_content\_sk\_ad\_network         |                                                                                                                                                                                                 |
| conversion\_add\_billing\_sk\_ad\_network          |                                                                                                                                                                                                 |
| conversion\_sign\_ups\_sk\_ad\_network             |                                                                                                                                                                                                 |
| conversion\_searches\_sk\_ad\_network              |                                                                                                                                                                                                 |
| conversion\_level\_completes\_sk\_ad\_network      |                                                                                                                                                                                                 |
| conversion\_app\_opens\_sk\_ad\_network            |                                                                                                                                                                                                 |
| conversion\_page\_views\_sk\_ad\_network           |                                                                                                                                                                                                 |
| conversion\_subscribe\_sk\_ad\_network             |                                                                                                                                                                                                 |
| conversion\_ad\_click\_sk\_ad\_network             |                                                                                                                                                                                                 |
| conversion\_ad\_view\_sk\_ad\_network              |                                                                                                                                                                                                 |
| conversion\_complete\_tutorial\_sk\_ad\_network    |                                                                                                                                                                                                 |
| conversion\_invite\_sk\_ad\_network                |                                                                                                                                                                                                 |
| conversion\_login\_sk\_ad\_network                 |                                                                                                                                                                                                 |
| conversion\_share\_sk\_ad\_network                 |                                                                                                                                                                                                 |
| conversion\_reserve\_sk\_ad\_network               |                                                                                                                                                                                                 |
| conversion\_achievement\_unlocked\_sk\_ad\_network |                                                                                                                                                                                                 |
| conversion\_add\_to\_wishlist\_sk\_ad\_network     |                                                                                                                                                                                                 |
| conversion\_spend\_credits\_sk\_ad\_network        |                                                                                                                                                                                                 |
| conversion\_rate\_sk\_ad\_network                  |                                                                                                                                                                                                 |
| conversion\_start\_trial\_sk\_ad\_network          |                                                                                                                                                                                                 |
| conversion\_list\_view\_sk\_ad\_network            |                                                                                                                                                                                                 |
| conversion\_visitation\_sk\_ad\_network            |                                                                                                                                                                                                 |
| custom\_event\_1\_sk\_ad\_network                  |                                                                                                                                                                                                 |
| custom\_event\_2\_sk\_ad\_network                  |                                                                                                                                                                                                 |
| custom\_event\_3\_sk\_ad\_network                  |                                                                                                                                                                                                 |
| custom\_event\_4\_sk\_ad\_network                  |                                                                                                                                                                                                 |
| custom\_event\_5\_sk\_ad\_network                  |                                                                                                                                                                                                 |
| unknown\_sk\_ad\_network                           | SkAdNetwork conversion events with unknown Conversion Values                                                                                                                                    |
| conversion\_assist\_install\_sk\_ad\_network       | The number of times the SKAdNetwork campaign drove an App Install, but was not the last touch before the App Install occurred. conversion\_null\_sk\_ad\_network                                |
| conversion\_null\_sk\_ad\_network                  | The number of SKAdNetwork conversion events with "null" Conversion Values. This indicates the campaign did not generate enough daily SKAdNetwork conversions to pass Apple’s privacy threshold. |

### SKAd Network View Conversion Metrics[​**](#skad-network-view-conversion-metrics "Copy to clipboard")

The following metrics return the SKAd Network VIEW conversions.

| Name                                                     | Description                                                                                                                                                                                    |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| conversion\_total\_installs\_sk\_ad\_network\_view       | Total App Installs tracked via SKAd Network                                                                                                                                                    |
| conversion\_ios\_installs\_sk\_ad\_network\_view         | Exact same metric as conversion\_total\_installs\_sk\_ad\_network\_view                                                                                                                        |
| conversion\_purchases\_sk\_ad\_network\_view             |                                                                                                                                                                                                |
| conversion\_save\_sk\_ad\_network\_view                  |                                                                                                                                                                                                |
| conversion\_start\_checkout\_sk\_ad\_network\_view       |                                                                                                                                                                                                |
| conversion\_add\_cart\_sk\_ad\_network\_view             |                                                                                                                                                                                                |
| conversion\_view\_content\_sk\_ad\_network\_view         |                                                                                                                                                                                                |
| conversion\_add\_billing\_sk\_ad\_network\_view          |                                                                                                                                                                                                |
| conversion\_sign\_ups\_sk\_ad\_network\_view             |                                                                                                                                                                                                |
| conversion\_searches\_sk\_ad\_network\_view              |                                                                                                                                                                                                |
| conversion\_level\_completes\_sk\_ad\_network\_view      |                                                                                                                                                                                                |
| conversion\_app\_opens\_sk\_ad\_network\_view            |                                                                                                                                                                                                |
| conversion\_page\_views\_sk\_ad\_network\_view           |                                                                                                                                                                                                |
| conversion\_subscribe\_sk\_ad\_network\_view             |                                                                                                                                                                                                |
| conversion\_ad\_click\_sk\_ad\_network\_view             |                                                                                                                                                                                                |
| conversion\_ad\_view\_sk\_ad\_network\_view              |                                                                                                                                                                                                |
| conversion\_complete\_tutorial\_sk\_ad\_network\_view    |                                                                                                                                                                                                |
| conversion\_invite\_sk\_ad\_network\_view                |                                                                                                                                                                                                |
| conversion\_login\_sk\_ad\_network\_view                 |                                                                                                                                                                                                |
| conversion\_share\_sk\_ad\_network\_view                 |                                                                                                                                                                                                |
| conversion\_reserve\_sk\_ad\_network\_view               |                                                                                                                                                                                                |
| conversion\_achievement\_unlocked\_sk\_ad\_network\_view |                                                                                                                                                                                                |
| conversion\_add\_to\_wishlist\_sk\_ad\_network\_view     |                                                                                                                                                                                                |
| conversion\_spend\_credits\_sk\_ad\_network\_view        |                                                                                                                                                                                                |
| conversion\_rate\_sk\_ad\_network\_view                  |                                                                                                                                                                                                |
| conversion\_start\_trial\_sk\_ad\_network\_view          |                                                                                                                                                                                                |
| conversion\_list\_view\_sk\_ad\_network\_view            |                                                                                                                                                                                                |
| conversion\_visitation\_sk\_ad\_network\_view            |                                                                                                                                                                                                |
| custom\_event\_1\_sk\_ad\_network\_view                  |                                                                                                                                                                                                |
| custom\_event\_2\_sk\_ad\_network\_view                  |                                                                                                                                                                                                |
| custom\_event\_3\_sk\_ad\_network\_view                  |                                                                                                                                                                                                |
| custom\_event\_4\_sk\_ad\_network\_view                  |                                                                                                                                                                                                |
| custom\_event\_5\_sk\_ad\_network\_view                  |                                                                                                                                                                                                |
| unknown\_sk\_ad\_network\_view                           | SkAdNetwork conversion events with unknown Conversion Values                                                                                                                                   |
| conversion\_assist\_install\_sk\_ad\_network\_view       | The number of times the SKAdNetwork campaign drove an App Install, but was not the last touch before the App Install occurred                                                                  |
| conversion\_null\_sk\_ad\_network\_view                  | The number of SKAdNetwork conversion events with "null" Conversion Values. This indicates the campaign did not generate enough daily SKAdNetwork conversions to pass Apple’s privacy threshold |

### SKAd Network Total Conversion Metrics[​**](#skad-network-total-conversion-metrics "Copy to clipboard")

The following metrics return the total sum of the SKAd Network SWIPE and VIEW conversions.

| Name                                                      | Description                                                                                                                                                                                    |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| conversion\_total\_installs\_sk\_ad\_network\_total       | Total App Installs tracked via SKAd Network                                                                                                                                                    |
| conversion\_ios\_installs\_sk\_ad\_network\_total         | Exact same metric as conversion\_total\_installs\_sk\_ad\_network\_total                                                                                                                       |
| conversion\_purchases\_sk\_ad\_network\_total             |                                                                                                                                                                                                |
| conversion\_save\_sk\_ad\_network\_total                  |                                                                                                                                                                                                |
| conversion\_start\_checkout\_sk\_ad\_network\_total       |                                                                                                                                                                                                |
| conversion\_add\_cart\_sk\_ad\_network\_total             |                                                                                                                                                                                                |
| conversion\_view\_content\_sk\_ad\_network\_total         |                                                                                                                                                                                                |
| conversion\_add\_billing\_sk\_ad\_network\_total          |                                                                                                                                                                                                |
| conversion\_sign\_ups\_sk\_ad\_network\_total             |                                                                                                                                                                                                |
| conversion\_searches\_sk\_ad\_network\_total              |                                                                                                                                                                                                |
| conversion\_level\_completes\_sk\_ad\_network\_total      |                                                                                                                                                                                                |
| conversion\_app\_opens\_sk\_ad\_network\_total            |                                                                                                                                                                                                |
| conversion\_page\_views\_sk\_ad\_network\_total           |                                                                                                                                                                                                |
| conversion\_subscribe\_sk\_ad\_network\_total             |                                                                                                                                                                                                |
| conversion\_ad\_click\_sk\_ad\_network\_total             |                                                                                                                                                                                                |
| conversion\_ad\_view\_sk\_ad\_network\_total              |                                                                                                                                                                                                |
| conversion\_complete\_tutorial\_sk\_ad\_network\_total    |                                                                                                                                                                                                |
| conversion\_invite\_sk\_ad\_network\_total                |                                                                                                                                                                                                |
| conversion\_login\_sk\_ad\_network\_total                 |                                                                                                                                                                                                |
| conversion\_share\_sk\_ad\_network\_total                 |                                                                                                                                                                                                |
| conversion\_reserve\_sk\_ad\_network\_total               |                                                                                                                                                                                                |
| conversion\_achievement\_unlocked\_sk\_ad\_network\_total |                                                                                                                                                                                                |
| conversion\_add\_to\_wishlist\_sk\_ad\_network\_total     |                                                                                                                                                                                                |
| conversion\_spend\_credits\_sk\_ad\_network\_total        |                                                                                                                                                                                                |
| conversion\_rate\_sk\_ad\_network\_total                  |                                                                                                                                                                                                |
| conversion\_start\_trial\_sk\_ad\_network\_total          |                                                                                                                                                                                                |
| conversion\_list\_view\_sk\_ad\_network\_total            |                                                                                                                                                                                                |
| conversion\_visitation\_sk\_ad\_network\_total            |                                                                                                                                                                                                |
| custom\_event\_1\_sk\_ad\_network\_total                  |                                                                                                                                                                                                |
| custom\_event\_2\_sk\_ad\_network\_total                  |                                                                                                                                                                                                |
| custom\_event\_3\_sk\_ad\_network\_total                  |                                                                                                                                                                                                |
| custom\_event\_4\_sk\_ad\_network\_total                  |                                                                                                                                                                                                |
| custom\_event\_5\_sk\_ad\_network\_total                  |                                                                                                                                                                                                |
| unknown\_sk\_ad\_network\_total                           | SkAdNetwork conversion events with unknown Conversion Values                                                                                                                                   |
| conversion\_assist\_install\_sk\_ad\_network\_total       | The number of times the SKAdNetwork campaign drove an App Install, but was not the last touch before the App Install occurred. conversion\_null\_sk\_ad\_network                               |
| conversion\_null\_sk\_ad\_network\_total                  | The number of SKAdNetwork conversion events with "null" Conversion Values. This indicates the campaign did not generate enough daily SKAdNetwork conversions to pass Apple’s privacy threshold |

## SKAd Network Conversion Example[​**](#skad-network-conversion-example "Copy to clipboard")

```
curl "https://adsapi.snapchat.com/v1/campaigns/5b483328-dfab-4321-be60-8ad2dfd63d35/stats?granularity=TOTAL&start_time=2021-01-21T00:00:00.000&end_time=2021-01-25T00:00:00.000&fields=impressions,spend,swipes,conversion_total_installs_sk_ad_network,conversion_purchases_sk_ad_network,conversion_add_cart_sk_ad_network"
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "SUCCESS",
  "request_id": "601d83ee00ff06ea9762c9c4f20001737e616473617069736300016275696c642d31323762373738342d312d3432302d3000010161",
  "total_stats": [
    {
      "sub_request_status": "SUCCESS",
      "total_stat": {
        "id": "5b483328-dfab-4321-be60-8ad2dfd63d35",
        "type": "CAMPAIGN",
        "granularity": "TOTAL",
        "stats": {
          "impressions": 61295,
          "swipes": 4528,
          "spend": 407129814,
          "conversion_total_installs_sk_ad_network": 1199,
          "conversion_purchases_sk_ad_network": 6637,
          "conversion_add_cart_sk_ad_network": 7212
        },
        "start_time": "2021-01-20T16:00:00.000-08:00",
        "end_time": "2021-01-24T16:00:00.000-08:00",
        "finalized_data_end_time": "2021-02-05T03:00:00.000-08:00"
      }
    }
  ]
}
```

This example fetches three specific SKAd Network conversion metrics.

## Conversion Reporting[​**](#conversion-reporting "Copy to clipboard")

The **action\_report\_time** parameter specifies the timing to use when requesting conversion reporting. Passing the value **conversion** will return conversions based on the time the user triggered the conversion event, passing the value **impression** will return conversions based on the time the ad impression took place.

Reporting for conversions based on ad impression (action\_report\_time=impression), are available from 1st May 2020 onwards.

## Conversion Event Stats[​**](#conversion-event-stats "Copy to clipboard")

The following conversion event metrics are available for ads that have been setup to track conversions through [Snap Pixel](#snap-pixel).

| Fields                                   | Granularity | Description                                                                                            |
| ---------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------ |
| conversion\_purchases                    | Any         | # of attributed "PURCHASE" conversion events                                                           |
| conversion\_purchases\_value             | Any         | Value of attributed "PURCHASE" conversion events (microcurrency in Ad Account's currency)              |
| conversion\_save                         | Any         | # of attributed "SAVE" conversion events                                                               |
| conversion\_save\_value                  | Any         | Value of attributed "SAVE" conversion events (microcurrency in Ad Account's currency)                  |
| conversion\_start\_checkout              | Any         | # of attributed "START\_CHECKOUT" conversion events                                                    |
| conversion\_start\_checkout\_value       | Any         | Value of attributed "START\_CHECKOUT" conversion events (microcurrency in Ad Account's currency)       |
| conversion\_add\_cart                    | Any         | # of attributed "ADD\_CART" conversion events                                                          |
| conversion\_add\_cart\_value             | Any         | Value of attributed "ADD\_CART" conversion events (microcurrency in Ad Account's currency)             |
| conversion\_view\_content                | Any         | # of attributed "VIEW\_CONTENT" conversion events                                                      |
| conversion\_view\_content\_value         | Any         | Value of attributed "VIEW\_CONTENT" conversion events (microcurrency in Ad Account's currency)         |
| conversion\_add\_billing                 | Any         | # of attributed "ADD\_BILLING" conversion events                                                       |
| conversion\_add\_billing\_value          | Any         | Value of attributed "ADD\_BILLING" conversion events (microcurrency in Ad Account's currency)          |
| conversion\_sign\_ups                    | Any         | # of attributed "SIGN\_UP" conversion events                                                           |
| conversion\_sign\_ups\_value             | Any         | Value of attributed "SIGN\_UP" conversion events (microcurrency in Ad Account's currency)              |
| conversion\_searches                     | Any         | # of attributed "SEARCH" conversion events                                                             |
| conversion\_searches\_value              | Any         | Value of attributed "SEARCH" conversion events (microcurrency in Ad Account's currency)                |
| conversion\_level\_completes             | Any         | # of attributed "LEVEL\_COMPLETE" conversion events                                                    |
| conversion\_level\_completes\_value      | Any         | Value of attributed "LEVEL\_COMPLETE" conversion events (microcurrency in Ad Account's currency)       |
| conversion\_app\_opens                   | Any         | # of attributed "APP\_OPEN" conversion events                                                          |
| conversion\_app\_opens\_value            | Any         | Value of attributed "APP\_OPEN" conversion events (microcurrency in Ad Account's currency)             |
| conversion\_page\_views                  | Any         | # of attributed "PAGE\_VIEW" conversion events                                                         |
| conversion\_page\_views\_value           | Any         | Value of attributed "PAGE\_VIEW" conversion events (microcurrency in Ad Account's currency)            |
| conversion\_subscribe                    | Any         | # of attributed "SUBSCRIBE" conversion events                                                          |
| conversion\_subscribe\_value             | Any         | Value of attributed "SUBSCRIBE" conversion events (microcurrency in Ad Account's currency)             |
| conversion\_ad\_click                    | Any         | # of attributed "AD\_CLICK" conversion events                                                          |
| conversion\_ad\_click\_value             | Any         | Value of attributed "AD\_CLICK" conversion events (microcurrency in Ad Account's currency)             |
| conversion\_ad\_view                     | Any         | # of attributed "AD\_VIEW" conversion events                                                           |
| conversion\_ad\_view\_value              | Any         | Value of attributed "AD\_VIEW" conversion events (microcurrency in Ad Account's currency)              |
| conversion\_complete\_tutorial           | Any         | # of attributed "COMPLETE\_TUTORIAL" conversion events                                                 |
| conversion\_complete\_tutorial\_value    | Any         | Value of attributed "COMPLETE\_TUTORIAL" conversion events (microcurrency in Ad Account's currency)    |
| conversion\_invite                       | Any         | # of attributed "INVITE" conversion events                                                             |
| conversion\_invite\_value                | Any         | Value of attributed "INVITE" conversion events (microcurrency in Ad Account's currency)                |
| conversion\_login                        | Any         | # of attributed "LOGIN" conversion events                                                              |
| conversion\_login\_value                 | Any         | Value of attributed "LOGIN" conversion events (microcurrency in Ad Account's currency)                 |
| conversion\_share                        | Any         | # of attributed "SHARE" conversion events                                                              |
| conversion\_share\_value                 | Any         | Value of attributed "SHARE" conversion events (microcurrency in Ad Account's currency)                 |
| conversion\_reserve                      | Any         | # of attributed "RESERVE" conversion events                                                            |
| conversion\_reserve\_value               | Any         | Value of attributed "RESERVE" conversion events (microcurrency in Ad Account's currency)               |
| conversion\_achievement\_unlocked        | Any         | # of attributed "ACHIEVEMENT\_UNLOCKED" conversion events                                              |
| conversion\_achievement\_unlocked\_value | Any         | Value of attributed "ACHIEVEMENT\_UNLOCKED" conversion events (microcurrency in Ad Account's currency) |
| conversion\_add\_to\_wishlist            | Any         | # of attributed "ADD\_TO\_WISHLIST" conversion events                                                  |
| conversion\_add\_to\_wishlist\_value     | Any         | Value of attributed "ADD\_TO\_WISHLIST" conversion events (microcurrency in Ad Account's currency)     |
| conversion\_spend\_credits               | Any         | # of attributed "SPENT\_CREDITS" conversion events                                                     |
| conversion\_spend\_credits\_value        | Any         | Value of attributed "SPENT\_CREDITS" conversion events (microcurrency in Ad Account's currency)        |
| conversion\_rate                         | Any         | # of attributed "RATE" conversion events                                                               |
| conversion\_rate\_value                  | Any         | Value of attributed "RATE" conversion events (microcurrency in Ad Account's currency)                  |
| conversion\_start\_trial                 | Any         | # of attributed "START\_TRIAL" conversion events                                                       |
| conversion\_start\_trial\_value          | Any         | Value of attributed "START\_TRIAL" conversion events (microcurrency in Ad Account's currency)          |
| conversion\_list\_view                   | Any         | # of attributed "LIST\_VIEW" conversion events                                                         |
| conversion\_list\_view\_value            | Any         | Value of attributed "LIST\_VIEW" conversion events (microcurrency in Ad Account's currency)            |
| conversion\_visit                        | Any         | # of attributed "VISIT" conversion events                                                              |
| conversion\_visit\_value                 | Any         | Value of attributed "VISIT" conversion events (microcurrency in Ad Account's currency)                 |
| custom\_event\_1                         | Any         | # of attributed "CUSTOM\_EVENT\_1" conversion events                                                   |
| custom\_event\_1\_value                  | Any         | Value of attributed "CUSTOM\_EVENT\_1" conversion events (microcurrency in Ad Account's currency)      |
| custom\_event\_2                         | Any         | # of attributed "CUSTOM\_EVENT\_2" conversion events                                                   |
| custom\_event\_2\_value                  | Any         | Value of attributed "CUSTOM\_EVENT\_2" conversion events (microcurrency in Ad Account's currency)      |
| custom\_event\_3                         | Any         | # of attributed "CUSTOM\_EVENT\_3" conversion events                                                   |
| custom\_event\_3\_value                  | Any         | Value of attributed "CUSTOM\_EVENT\_3" conversion events (microcurrency in Ad Account's currency)      |
| custom\_event\_4                         | Any         | # of attributed "CUSTOM\_EVENT\_4" conversion events                                                   |
| custom\_event\_4\_value                  | Any         | Value of attributed "CUSTOM\_EVENT\_4" conversion events (microcurrency in Ad Account's currency)      |
| custom\_event\_5                         | Any         | # of attributed "CUSTOM\_EVENT\_5" conversion events                                                   |
| custom\_event\_5\_value                  | Any         | Value of attributed "CUSTOM\_EVENT\_5" conversion events (microcurrency in Ad Account's currency)      |

## Custom Conversions[​**](#custom-conversions "Copy to clipboard")

If you are using Custom Conversions, metrics are available using the conversion ID.

### Fetch Custom Conversion IDs[​**](#fetch-custom-conversion-ids "Copy to clipboard")

Custom conversions are created under the event source that they are reported via, for web events they will be created under the Pixel Entity. To fetch all custom conversions that have been defined under a specific pixel you should use this method.

**Pattern:**

```
GET /pixels/{pixel_id}/custom_conversions
```

### Reporting Restrictions[​**](#reporting-restrictions "Copy to clipboard")

Custom conversions can be requested at all levels (Ad Account, Campaign, Ad Set, Ad), with all parameters and granularities, with the exception of `report_dimension` (insights), the report\_dimension parameter cannot be used with custom conversions.

### Example I: Fetch Custom Conversions via event source[​**](#example-i-fetch-custom-conversions-via-event-source "Copy to clipboard")

**Request:**

```
curl https://adsapi.snapchat.com/v1/pixels/82225ba6-7559-4000-9663-bace8adff5f8/custom_conversions
  -H "Authorization: Bearer meowmeowmeow"
```

**Response:**

```
{
  "request_status": "SUCCESS",
  "request_id": "631a177c-5068-475f-ad08-0622243df1e6",
  "paging": {},
  "custom_conversions": [
    {
      "sub_request_status": "SUCCESS",
      "custom_conversion": {
        "id": "0029904941",
        "updated_at": "2023-07-20T21:25:11.550Z",
        "created_at": "2023-07-12T21:58:21.425Z",
        "event_source": {
          "id": "82225ba6-7559-4000-9663-bace8adff5f8",
          "type": "PIXEL"
        },
        "name": "kitten_sales",
        "description": "Recording all kitten purchases",
        "event_type": "PURCHASE",
        "rules": [
          {
            "key": "BRAND",
            "values": ["kitten"],
            "operator": "I_CONTAINS"
          }
        ]
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "custom_conversion": {
        "id": "1828361131",
        "updated_at": "2023-07-18T07:16:28.440Z",
        "created_at": "2023-07-12T21:56:57.705Z",
        "event_source": {
          "id": "82225ba6-7559-4000-9663-bace8adff5f8",
          "type": "PIXEL"
        },
        "name": "european_puppy_sales",
        "description": "Recording country specific Puppy Purchases for Germany/France/Italy",
        "event_type": "PURCHASE",
        "rules": [
          {
            "key": "BRAND",
            "values": ["puppy"],
            "operator": "CONTAINS"
          },
          {
            "key": "EVENT_TAG",
            "values": ["DE", "FR", "IT"],
            "operator": "CONTAINS"
          }
        ]
      }
    }
  ]
}
```

Show more▼

Once you have the ID value of a custom conversion, you can use it to fetch reporting for the Custom Conversion via the Marketing API. You need to prepend the term `conversion_` to the ID of the custom conversion.

Example of how to create the ID for reporting using two custom conversions:

| Custom Conversion Name | Custom Conversion ID | ID for reporting       |
| ---------------------- | -------------------- | ---------------------- |
| kitten\_sales          | 0029904941           | conversion\_0029904941 |
| european\_puppy\_sales | 1828361131           | conversion\_1828361131 |

The custom conversion IDs would look the following way when used to fetch reporting. This value is passed via the `fields` parameter.

If you have set up your events in Conversions API v3 to use the contents attribute to pass id, quantity, item\_price, and brand for each item sold in the `PURCHASE` event, you can also fetch reporting on the value of the sales of each Custom Conversion. This is achieved by adding `_value` to the reporting ID.

| Custom Conversion Name | Custom Conversion ID | ID for reporting value        |
| ---------------------- | -------------------- | ----------------------------- |
| kitten\_sales          | 0029904941           | conversion\_0029904941\_value |
| european\_puppy\_sales | 1828361131           | conversion\_1828361131\_value |

**Pattern:**

```
GET /adaccounts/{ad_account_id}/stats
```

### Example II - API reporting request by Campaign[​**](#example-ii---api-reporting-request-by-campaign "Copy to clipboard")

Fetch custom conversions (`conversion_0029904941` & `conversion_1828361131`) broken into Campaign.

**Request:**

```
curl "https://adsapi.snapchat.com/v1/adaccounts/52b56e53-2c90-426c-af68-8bc12a472fa1/stats?\
granularity=TOTAL&\
breakdown=campaign&\
fields=impressions,swipes,conversion_0029904941,conversion_0029904941_value,conversion_1828361131,conversion_1828361131_value"
-H "Authorization: Bearer meowmeowmeow"
```

**Response:**

```
{
  "request_status": "SUCCESS",
  "request_id": "7aff1136-7a77-4111-b6bf-b3e1e3072b3c",
  "total_stats": [
    {
      "sub_request_status": "SUCCESS",
      "total_stat": {
        "id": "52b56e53-2c90-426c-af68-8bc12a472fa1",
        "type": "AD_ACCOUNT",
        "granularity": "TOTAL",
        "swipe_up_attribution_window": "28_DAY",
        "view_attribution_window": "1_DAY",
        "end_time": "2023-08-02T14:00:00.000-07:00",
        "finalized_data_end_time": "2023-08-02T07:00:00.000-07:00",
        "conversion_data_processed_end_time": "2023-08-01T12:00:00.000Z",
        "breakdown_stats": {
          "campaign": [
            {
              "id": "2249077d-b714-4088-860d-c06b4dbe53a2",
              "type": "CAMPAIGN",
              "granularity": "TOTAL",
              "stats": {
                "impressions": 1235768,
                "swipes": 11759,
                "conversion_0029904941": 14,
                "conversion_1828361131": 10,
                "conversion_0029904941_value": 2345,
                "conversion_1828361131_value": 678
              }
            }
          ]
        }
      }
    }
  ]
}
```

Show more▼

### Example III - API reporting request Swipe and View[​**](#example-iii---api-reporting-request-swipe-and-view "Copy to clipboard")

An example breaking the custom conversions into swipe and view.

**Request:**

```
curl "https://adsapi.snapchat.com/v1/adaccounts/52b56e53-2c90-426c-af68-8bc12a472fa1/stats?\
granularity=TOTAL&\
fields=impressions,swipes,conversion_0029904941,conversion_0029904941_swipe,conversion_0029904941_view,conversion_1828361131,conversion_1828361131_swipe,conversion_1828361131_view&\
swipe_up_attribution_window=28_DAY&\
view_attribution_window=1_DAY"
-H "Authorization: Bearer meowmeowmeow"
```

**Response:**

```
{
  "request_status": "SUCCESS",
  "request_id": "9bff1136-7a77-4111-b6bf-b3e1e3072b4a",
  "total_stats": [
    {
      "sub_request_status": "SUCCESS",
      "total_stat": {
        "id": "52b56e53-2c90-426c-af68-8bc12a472fa1",
        "type": "AD_ACCOUNT",
        "granularity": "TOTAL",
        "swipe_up_attribution_window": "28_DAY",
        "view_attribution_window": "1_DAY",
        "end_time": "2023-08-02T14:00:00.000-07:00",
        "finalized_data_end_time": "2023-08-02T07:00:00.000-07:00",
        "conversion_data_processed_end_time": "2023-08-01T12:00:00.000Z",
        "breakdown_stats": {
          "campaign": [
            {
              "id": "2249077d-b714-4088-860d-c06b4dbe53a2",
              "type": "CAMPAIGN",
              "granularity": "TOTAL",
              "stats": {
                "impressions": 1235768,
                "swipes": 11759,
                "conversion_0029904941": 14,
                "conversion_0029904941_swipe": 7,
                "conversion_0029904941_view": 7,
                "conversion_1828361131": 10,
                "conversion_1828361131_swipe": 4,
                "conversion_1828361131_view": 6
              }
            }
          ]
        }
      }
    }
  ]
}
```

Show more▼

## Conversion breakout[​**](#conversion-breakout "Copy to clipboard")

The parameter **conversion\_source\_types** provides a breakout of conversions based on where the conversions occurred.

| Parameter            | Description                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------- |
| total                | All conversion events                                                                     |
| web                  | Events reported via the Snap Pixel SDK                                                    |
| app                  | Events reported within an App                                                             |
| mmp                  | **Unified conversions only:** Events reported by a Mobile Measurement Partner             |
| offline              | Events reported from an offline source (in-store)                                         |
| total                | The combined events reported for web, app, offline, and on platform (Stores and Profiles) |
| total\_off\_platform | The combined events reported for web, app, and offline                                    |
| total\_on\_platform  | Events reported from a Snap platform source (Stores and Profiles)                         |

### Example 1 - Conversion breakout total, web and app[​**](#example-1---conversion-breakout-total-web-and-app "Copy to clipboard")

The `conversion_source_types` parameter breaks down conversions based on where the conversion occurred.

```
curl "https://adsapi.snapchat.com/v1/adsquads/0b7e62aa-a8bc-48f6-a410-c65eee9cc9a7/stats?fields=conversion_purchases,impressions,spend,swipe_up_percent,swipes,view_completion&conversion_source_types=total,web,app"
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "SUCCESS",
  "request_id": "5de004c100ff03ea1eeb1050430001737e616473617069736300016275696c642d61663733336133322d312d3330372d3000010103",
  "total_stats": [
    {
      "sub_request_status": "SUCCESS",
      "total_stat": {
        "id": "0b7e62aa-a8bc-48f6-a410-c65eee9cc9a7",
        "type": "AD_SQUAD",
        "granularity": "TOTAL",
        "stats": {
          "impressions": 2337371,
          "swipes": 14745,
          "view_completion": 69506,
          "swipe_up_percent": 0.0063,
          "spend": 3449137066,
          "conversion_purchases": 1141,
          "conversion_purchases_web": 659,
          "conversion_purchases_app": 482
        },
        "finalized_data_end_time": "2019-11-28T02:00:00.000-08:00"
      }
    }
  ]
}
```

### Example 2 - Empty records - Conversion breakout total, web and app[​**](#example-2---empty-records---conversion-breakout-total-web-and-app "Copy to clipboard")

This example returns several day entries with no metrics attached to them.

```
curl "https://adsapi.snapchat.com/v1/campaigns/9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37/stats?granularity=DAY&start_time=2019-11-12T00%3A00%3A00-08%3A00&end_time=2019-11-16T00%3A00%3A00-08%3A00&&swipe_up_attribution_window=28_DAY&view_attribution_window=7_DAY&fields=conversion_purchases,impressions,swipes,spend&conversion_source_types=web,app,total"
  -H "Authorization: Bearer meowmeowmeow"
```

```
{
  "request_status": "SUCCESS",
  "request_id": "5de0f99900ff02f49ea1540d1c0001737e616473617069736300016275696c642d61663733336133322d312d3330372d300001013c",
  "timeseries_stats": [
    {
      "sub_request_status": "SUCCESS",
      "timeseries_stat": {
        "id": "9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37",
        "type": "CAMPAIGN",
        "granularity": "DAY",
        "swipe_up_attribution_window": "28_DAY",
        "view_attribution_window": "7_DAY",
        "start_time": "2019-11-12T00:00:00.000-08:00",
        "end_time": "2019-11-16T00:00:00.000-08:00",
        "finalized_data_end_time": "2019-11-28T00:00:00.000-08:00",
        "timeseries": [
          {
            "start_time": "2019-11-12T00:00:00.000-08:00",
            "end_time": "2019-11-13T00:00:00.000-08:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "conversion_purchases": 0,
              "conversion_purchases_web": 0,
              "conversion_purchases_app": 0
            }
          },
          {
            "start_time": "2019-11-13T00:00:00.000-08:00",
            "end_time": "2019-11-14T00:00:00.000-08:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "conversion_purchases": 0,
              "conversion_purchases_web": 0,
              "conversion_purchases_app": 0
            }
          },
          {
            "start_time": "2019-11-14T00:00:00.000-08:00",
            "end_time": "2019-11-15T00:00:00.000-08:00",
            "stats": {
              "impressions": 599725,
              "swipes": 3790,
              "spend": 594736665,
              "conversion_purchases": 62,
              "conversion_purchases_web": 42,
              "conversion_purchases_app": 20
            }
          },
          {
            "start_time": "2019-11-15T00:00:00.000-08:00",
            "end_time": "2019-11-16T00:00:00.000-08:00",
            "stats": {
              "impressions": 670692,
              "swipes": 4189,
              "spend": 716170632,
              "conversion_purchases": 125,
              "conversion_purchases_web": 82,
              "conversion_purchases_app": 43
            }
          }
        ]
      }
    }
  ]
}
```

Show more▼

### Example 3 - Omitting empty records - Conversion breakout total, web and app[​**](#example-3---omitting-empty-records---conversion-breakout-total-web-and-app "Copy to clipboard")

This example runs across the same days as example 2 but since the `omit_empty=true` has been attached to the request the days with no conversions are not returned.

The parameter `omit_empty` will omit records with zero data for all metrics for a given date/entity. If there is data for any metric for a given date/entity, all metrics for that date/entity are returned.

The `omit_empty` parameter allows developers to speed up calculations as empty entries can be removed before the calculation is made, it also allows developers to structure an app to avoid displaying empty entries in the UI.

```
curl "https://adsapi.snapchat.com/v1/campaigns/9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37/stats?granularity=DAY&start_time=2019-11-12T00%3A00%3A00-08%3A00&end_time=2019-11-16T00%3A00%3A00-08%3A00&&swipe_up_attribution_window=28_DAY&view_attribution_window=7_DAY&fields=conversion_purchases,impressions,swipes,spend&conversion_source_types=web,app,total&omit_empty=true"
  -H "Authorization: Bearer meowmeowmeow"
```

> An example using omit\_empty, this returns only day entries with metrics:

```
{
  "request_status": "SUCCESS",
  "request_id": "5de0fa4900ff0942bb5374cb8f0001737e616473617069736300016275696c642d61663733336133322d312d3330372d300001014d",
  "timeseries_stats": [
    {
      "sub_request_status": "SUCCESS",
      "timeseries_stat": {
        "id": "9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37",
        "type": "CAMPAIGN",
        "granularity": "DAY",
        "swipe_up_attribution_window": "28_DAY",
        "view_attribution_window": "7_DAY",
        "start_time": "2019-11-12T00:00:00.000-08:00",
        "end_time": "2019-11-16T00:00:00.000-08:00",
        "finalized_data_end_time": "2019-11-28T00:00:00.000-08:00",
        "timeseries": [
          {
            "start_time": "2019-11-14T00:00:00.000-08:00",
            "end_time": "2019-11-15T00:00:00.000-08:00",
            "stats": {
              "impressions": 599725,
              "swipes": 3790,
              "spend": 594736665,
              "conversion_purchases": 62,
              "conversion_purchases_web": 42,
              "conversion_purchases_app": 20
            }
          },
          {
            "start_time": "2019-11-15T00:00:00.000-08:00",
            "end_time": "2019-11-16T00:00:00.000-08:00",
            "stats": {
              "impressions": 670692,
              "swipes": 4189,
              "spend": 716170632,
              "conversion_purchases": 125,
              "conversion_purchases_web": 82,
              "conversion_purchases_app": 43
            }
          }
        ]
      }
    }
  ]
}
```

Show more▼

## Unified Attribution metrics[​**](#unified-attribution-metrics "Copy to clipboard")

Reporting for Campaigns using the Unified attribution logic follows a number of rules:

* MMP breakdown is automatically included when the parameter `conversion_source_types=app` is included in the reporting request

* The MMP conversion window is fixed and managed in the MMP settings (Adjust, Appsflyer) This means that the MMP conversions returned in the report will not change when the parameters `swipe_up_attribution_window` and `view_attribution_window` are adjusted

* Reporting insights (`report_dimension`) are available for the MMP metrics for the following combinations

  * age
  * gender
  * age,gender
  * country
  * os

### Unified install metrics[​**](#unified-install-metrics "Copy to clipboard")

These install metrics are broken into app and mmp when using `conversion_source_types=app` for a Campaign that used the Unified conversion logic.

| Regular                  | app breakout                  | Automatic mmp breakout        |
| ------------------------ | ----------------------------- | ----------------------------- |
| total\_installs          | total\_installs\_app          | total\_installs\_mmp          |
| total\_installs\_value   | total\_installs\_value\_app   | total\_installs\_mmp\_value   |
| ios\_installs            | ios\_installs\_app            | ios\_installs\_mmp            |
| ios\_installs\_value     | ios\_installs\_value\_app     | ios\_installs\_mmp\_value     |
| android\_installs        | android\_installs\_app        | android\_installs\_mmp        |
| android\_installs\_value | android\_installs\_value\_app | android\_installs\_mmp\_value |

### Unified conversion metrics[​**](#unified-conversion-metrics "Copy to clipboard")

These conversion metrics are broken into app and mmp when using `conversion_source_types=app` for a Campaign that used the Unified conversion logic.

| Metric                                   | Using conversion\_source\_types=app           | Automatic mmp breakout                                         |
| ---------------------------------------- | --------------------------------------------- | -------------------------------------------------------------- |
| conversion\_achievement\_unlocked        | conversion\_achievement\_unlocked\_app        | conversion\_achievement\_unlocked\_paired\_install\_mmp        |
| conversion\_achievement\_unlocked\_value | conversion\_achievement\_unlocked\_value\_app | conversion\_achievement\_unlocked\_paired\_install\_mmp\_value |
| conversion\_ad\_click                    | conversion\_ad\_click\_app                    | conversion\_ad\_click\_paired\_install\_mmp                    |
| conversion\_ad\_click\_value             | conversion\_ad\_click\_value\_app             | conversion\_ad\_click\_paired\_install\_mmp\_value             |
| conversion\_ad\_view                     | conversion\_ad\_view\_app                     | conversion\_ad\_view\_paired\_install\_mmp                     |
| conversion\_ad\_view\_value              | conversion\_ad\_view\_value\_app              | conversion\_ad\_view\_paired\_install\_mmp\_value              |
| conversion\_add\_billing                 | conversion\_add\_billing\_app                 | conversion\_add\_billing\_paired\_install\_mmp                 |
| conversion\_add\_billing\_value          | conversion\_add\_billing\_value\_app          | conversion\_add\_billing\_paired\_install\_mmp\_value          |
| conversion\_add\_cart                    | conversion\_add\_cart\_app                    | conversion\_add\_cart\_paired\_install\_mmp                    |
| conversion\_add\_cart\_value             | conversion\_add\_cart\_value\_app             | conversion\_add\_cart\_paired\_install\_mmp\_value             |
| conversion\_add\_to\_wishlist            | conversion\_add\_to\_wishlist\_app            | conversion\_add\_to\_wishlist\_paired\_install\_mmp            |
| conversion\_add\_to\_wishlist\_value     | conversion\_add\_to\_wishlist\_value\_app     | conversion\_add\_to\_wishlist\_paired\_install\_mmp\_value     |
| conversion\_app\_opens                   | conversion\_app\_opens\_app                   | conversion\_app\_opens\_paired\_install\_mmp                   |
| conversion\_app\_opens\_value            | conversion\_app\_opens\_value\_app            | conversion\_app\_opens\_paired\_install\_mmp\_value            |
| conversion\_complete\_tutorial           | conversion\_complete\_tutorial\_app           | conversion\_complete\_tutorial\_paired\_install\_mmp           |
| conversion\_complete\_tutorial\_value    | conversion\_complete\_tutorial\_value\_app    | conversion\_complete\_tutorial\_paired\_install\_mmp\_value    |
| conversion\_invite                       | conversion\_invite\_app                       | conversion\_invite\_paired\_install\_mmp                       |
| conversion\_invite\_value                | conversion\_invite\_value\_app                | conversion\_invite\_paired\_install\_mmp\_value                |
| conversion\_level\_completes             | conversion\_level\_completes\_app             | conversion\_level\_completes\_paired\_install\_mmp             |
| conversion\_level\_completes\_value      | conversion\_level\_completes\_value\_app      | conversion\_level\_completes\_paired\_install\_mmp\_value      |
| conversion\_list\_view                   | conversion\_list\_view\_app                   | conversion\_list\_view\_paired\_install\_mmp                   |
| conversion\_list\_view\_value            | conversion\_list\_view\_value\_app            | conversion\_list\_view\_paired\_install\_mmp\_value            |
| conversion\_login                        | conversion\_login\_app                        | conversion\_login\_paired\_install\_mmp                        |
| conversion\_login\_value                 | conversion\_login\_value\_app                 | conversion\_login\_paired\_install\_mmp\_value                 |
| conversion\_page\_views                  | conversion\_page\_views\_app                  | conversion\_page\_views\_paired\_install\_mmp                  |
| conversion\_page\_views\_value           | conversion\_page\_views\_value\_app           | conversion\_page\_views\_paired\_install\_mmp\_value           |
| conversion\_promotion\_card\_add         | conversion\_promotion\_card\_add\_app         | conversion\_promotion\_card\_add\_paired\_install\_mmp         |
| conversion\_promotion\_card\_add\_value  | conversion\_promotion\_card\_add\_value\_app  | conversion\_promotion\_card\_add\_paired\_install\_mmp\_value  |
| conversion\_promotion\_card\_view        | conversion\_promotion\_card\_view\_app        | conversion\_promotion\_card\_view\_paired\_install\_mmp        |
| conversion\_promotion\_card\_view\_value | conversion\_promotion\_card\_view\_value\_app | conversion\_promotion\_card\_view\_paired\_install\_mmp\_value |
| conversion\_promotion\_view              | conversion\_promotion\_view\_app              | conversion\_promotion\_view\_paired\_install\_mmp              |
| conversion\_promotion\_view\_value       | conversion\_promotion\_view\_value\_app       | conversion\_promotion\_view\_paired\_install\_mmp\_value       |
| conversion\_purchases                    | conversion\_purchases\_app                    | conversion\_purchases\_paired\_install\_mmp                    |
| conversion\_purchases\_value             | conversion\_purchases\_value\_app             | conversion\_purchases\_paired\_install\_mmp\_value             |
| conversion\_rate                         | conversion\_rate\_app                         | conversion\_rate\_paired\_install\_mmp                         |
| conversion\_rate\_value                  | conversion\_rate\_value\_app                  | conversion\_rate\_paired\_install\_mmp\_value                  |
| conversion\_reinstall                    | conversion\_reinstall\_app                    | conversion\_reinstall\_paired\_install\_mmp                    |
| conversion\_reinstall\_value             | conversion\_reinstall\_value\_app             | conversion\_reinstall\_paired\_install\_mmp\_value             |
| conversion\_reserve                      | conversion\_reserve\_app                      | conversion\_reserve\_paired\_install\_mmp                      |
| conversion\_reserve\_value               | conversion\_reserve\_value\_app               | conversion\_reserve\_paired\_install\_mmp\_value               |
| conversion\_save                         | conversion\_save\_app                         | conversion\_save\_paired\_install\_mmp                         |
| conversion\_save\_value                  | conversion\_save\_value\_app                  | conversion\_save\_paired\_install\_mmp\_value                  |
| conversion\_searches                     | conversion\_searches\_app                     | conversion\_searches\_paired\_install\_mmp                     |
| conversion\_searches\_value              | conversion\_searches\_value\_app              | conversion\_searches\_paired\_install\_mmp\_value              |
| conversion\_share                        | conversion\_share\_app                        | conversion\_share\_paired\_install\_mmp                        |
| conversion\_share\_value                 | conversion\_share\_value\_app                 | conversion\_share\_paired\_install\_mmp\_value                 |
| conversion\_sign\_ups                    | conversion\_sign\_ups\_app                    | conversion\_sign\_ups\_paired\_install\_mmp                    |
| conversion\_sign\_ups\_value             | conversion\_sign\_ups\_value\_app             | conversion\_sign\_ups\_paired\_install\_mmp\_value             |
| conversion\_spend\_credits               | conversion\_spend\_credits\_app               | conversion\_spend\_credits\_paired\_install\_mmp               |
| conversion\_spend\_credits\_value        | conversion\_spend\_credits\_value\_app        | conversion\_spend\_credits\_paired\_install\_mmp\_value        |
| conversion\_start\_checkout              | conversion\_start\_checkout\_app              | conversion\_start\_checkout\_paired\_install\_mmp              |
| conversion\_start\_checkout\_value       | conversion\_start\_checkout\_value\_app       | conversion\_start\_checkout\_paired\_install\_mmp\_value       |
| conversion\_start\_trial                 | conversion\_start\_trial\_app                 | conversion\_start\_trial\_paired\_install\_mmp                 |
| conversion\_start\_trial\_value          | conversion\_start\_trial\_value\_app          | conversion\_start\_trial\_paired\_install\_mmp\_value          |
| conversion\_subscribe                    | conversion\_subscribe\_app                    | conversion\_subscribe\_paired\_install\_mmp                    |
| conversion\_subscribe\_value             | conversion\_subscribe\_value\_app             | conversion\_subscribe\_paired\_install\_mmp\_value             |
| conversion\_view\_content                | conversion\_view\_content\_app                | conversion\_view\_content\_paired\_install\_mmp                |
| conversion\_view\_content\_value         | conversion\_view\_content\_value\_app         | conversion\_view\_content\_paired\_install\_mmp\_value         |
| conversion\_visit                        | conversion\_visit\_app                        | conversion\_visit\_paired\_install\_mmp                        |
| conversion\_visit\_value                 | conversion\_visit\_value\_app                 | conversion\_visit\_paired\_install\_mmp\_value                 |

### Unified custom event conversion metrics[​**](#unified-custom-event-conversion-metrics "Copy to clipboard")

These custom event conversion metrics are broken into app and mmp when using `conversion_source_types=app` for a Campaign that used the Unified conversion logic.

| Metric                  | Using conversion\_source\_types=app | Automatic mmp breakout                        |
| ----------------------- | ----------------------------------- | --------------------------------------------- |
| custom\_event\_1        | custom\_event\_1\_app               | custom\_event\_1\_paired\_install\_mmp        |
| custom\_event\_1\_value | custom\_event\_1\_value\_app        | custom\_event\_1\_paired\_install\_mmp\_value |
| custom\_event\_2        | custom\_event\_2\_app               | custom\_event\_2\_paired\_install\_mmp        |
| custom\_event\_2\_value | custom\_event\_2\_value\_app        | custom\_event\_2\_paired\_install\_mmp\_value |
| custom\_event\_3        | custom\_event\_3\_app               | custom\_event\_3\_paired\_install\_mmp        |
| custom\_event\_3\_value | custom\_event\_3\_value\_app        | custom\_event\_3\_paired\_install\_mmp\_value |
| custom\_event\_4        | custom\_event\_4\_app               | custom\_event\_4\_paired\_install\_mmp        |
| custom\_event\_4\_value | custom\_event\_4\_value\_app        | custom\_event\_4\_paired\_install\_mmp\_value |
| custom\_event\_5        | custom\_event\_5\_app               | custom\_event\_5\_paired\_install\_mmp        |
| custom\_event\_5\_value | custom\_event\_5\_value\_app        | custom\_event\_5\_paired\_install\_mmp\_value |

### Example 1 - Unified conversions breakout total, app and mmp[​**](#example-1---unified-conversions-breakout-total-app-and-mmp "Copy to clipboard")

When requesting `conversion_source_types=app` for an entity that was using the Unified attribution logic the response will contain App conversions (Snapchat) and MMP (Mobile Measurement Partner) attributed conversions.

In this example we request the metrics `total_installs` and `conversion_purchases`, since this Campaign used the Unified attribution setting it automatically also returns the MMP metrics `total_installs_mmp` and `conversion_purchases_paired_install_mmp`.

```
curl "https://adsapi.snapchat.com/v1/campaigns/ad3f86c7-c2e8-4f73-940d-0edbb0524bb6/stats?swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY&start_time=2026-07-01&end_time=2026-07-31&granularity=TOTAL&conversion_source_types=total,app&fields=impressions,spend,total_installs,conversion_purchases"
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "SUCCESS",
  "request_id": "ca29d98e-0399-4e63-89e8-8aa1f938e57f",
  "total_stats": [
    {
      "sub_request_status": "SUCCESS",
      "total_stat": {
        "id": "ad3f86c7-c2e8-4f73-940d-0edbb0524bb6",
        "type": "CAMPAIGN",
        "granularity": "TOTAL",
        "swipe_up_attribution_window": "28_DAY",
        "view_attribution_window": "1_DAY",
        "stats": {
          "impressions": 42062270,
          "spend": 4230230000,
          "total_installs": 2748,
          "conversion_purchases": 302206,
          "conversion_purchases_paired_install_mmp": 409327,
          "conversion_purchases_app": 302206,
          "total_installs_app": 2748,
          "total_installs_mmp": 5053
        },
        "start_time": "2026-07-01T00:00:00.000+08:00",
        "end_time": "2026-07-31T00:00:00.000+08:00",
        "finalized_data_end_time": "2026-08-28T12:00:00.000Z",
        "conversion_data_processed_end_time": "2026-08-27T00:00:00.000Z"
      }
    }
  ]
}
```

### Example 2 - Unified conversions breakout with insights total, app and mmp[​**](#example-2---unified-conversions-breakout-with-insights-total-app-and-mmp "Copy to clipboard")

Note how this request uses `conversion_source_types=total,app` asking for `total_installs` and `conversion_purchases` broken down by age `report_dimension=age`

The response includes both `total_installs_app`, `total_installs_mmp`, `conversion_purchases_app` and `conversion_purchases_paired_install_mmp`, all broken into age buckets.

```
curl "https://adsapi.snapchat.com/v1/campaigns/fd3f76c7-c2e8-4f73-940d-0edbb0524ba4/stats?swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY&start_time=2026-07-01&end_time=2026-07-31&granularity=TOTAL&conversion_source_types=total,app&report_dimension=age&fields=impressions,spend,total_installs,conversion_purchases"
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "SUCCESS",
  "request_id": "b0eecb2f-be9a-4ca2-8b6f-5f2421010628",
  "total_stats": [
    {
      "sub_request_status": "SUCCESS",
      "total_stat": {
        "id": "fd3f76c7-c2e8-4f73-940d-0edbb0524ba4",
        "type": "CAMPAIGN",
        "granularity": "TOTAL",
        "swipe_up_attribution_window": "28_DAY",
        "view_attribution_window": "1_DAY",
        "engaged_view_attribution_window": "2_DAY",
        "start_time": "2026-07-01T00:00:00.000+08:00",
        "end_time": "2026-07-31T00:00:00.000+08:00",
        "finalized_data_end_time": "2026-08-26T10:00:00.000Z",
        "conversion_data_processed_end_time": "2026-08-25T00:00:00.000Z",
        "dimension_stats": [
          {
            "impressions": 4613848,
            "spend": 280420806,
            "age_bucket": "13-17",
            "total_installs": 989,
            "conversion_purchases": 5313,
            "conversion_purchases_paired_install_mmp": 8386,
            "conversion_purchases_app": 5091,
            "total_installs_app": 666,
            "total_installs_mmp": 1061
          },
          {
            "impressions": 8697325,
            "spend": 798229990,
            "age_bucket": "18-20",
            "total_installs": 328,
            "conversion_purchases": 17799,
            "conversion_purchases_paired_install_mmp": 33234,
            "conversion_purchases_app": 6317,
            "total_installs_app": 120,
            "total_installs_mmp": 715
          },
          {
            "impressions": 9170646,
            "spend": 810438476,
            "age_bucket": "21-24",
            "total_installs": 224,
            "conversion_purchases": 21978,
            "conversion_purchases_paired_install_mmp": 47084,
            "conversion_purchases_app": 6273,
            "total_installs_app": 81,
            "total_installs_mmp": 670
          },
          {
            "impressions": 12668641,
            "spend": 1252910294,
            "age_bucket": "25-34",
            "total_installs": 394,
            "conversion_purchases": 49005,
            "conversion_purchases_paired_install_mmp": 91806,
            "conversion_purchases_app": 10145,
            "total_installs_app": 141,
            "total_installs_mmp": 1085
          },
          {
            "impressions": 6809136,
            "spend": 1079924882,
            "age_bucket": "35+",
            "total_installs": 363,
            "conversion_purchases": 153134,
            "conversion_purchases_paired_install_mmp": 139573,
            "conversion_purchases_app": 0,
            "total_installs_app": 0,
            "total_installs_mmp": 799
          },
          {
            "impressions": 5335300,
            "spend": 787221591,
            "age_bucket": "35-44",
            "total_installs": 369,
            "conversion_purchases": 106968,
            "conversion_purchases_paired_install_mmp": 129441,
            "conversion_purchases_app": 26590,
            "total_installs_app": 98,
            "total_installs_mmp": 740
          },
          {
            "impressions": 1038161,
            "spend": 191889656,
            "age_bucket": "45-54",
            "total_installs": 84,
            "conversion_purchases": 61483,
            "conversion_purchases_paired_install_mmp": 45485,
            "conversion_purchases_app": 16070,
            "total_installs_app": 21,
            "total_installs_mmp": 171
          },
          {
            "impressions": 435675,
            "spend": 100813635,
            "age_bucket": "55+",
            "total_installs": 39,
            "conversion_purchases": 36340,
            "conversion_purchases_paired_install_mmp": 14548,
            "conversion_purchases_app": 8997,
            "total_installs_app": 10,
            "total_installs_mmp": 64
          }
        ]
      }
    }
  ]
}
```

Show more▼

## Metrics and supported granularities[​**](#metrics-and-supported-granularities "Copy to clipboard")

| Metric                                   | Real time | HOUR                                                                        | DAY                                                                         | TOTAL                                                                                                                                                         | LIFETIME                                         |
| ---------------------------------------- | --------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| android\_installs                        | YES       | YES. time must be of hour boundary, start\_time and end\_time within 7 days | YES. time must be of day boundary, start\_time and end\_time within 31 days | YES. time must be of day boundary, start\_time and end\_time must be both specified, or neither. In the latter case, it combines lifetime and realtime stats. | YES. no start\_time, end\_time can be specified. |
| attachment\_avg\_view\_time\_millis      |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| attachment\_impressions                  |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| attachment\_quartile\_1                  |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| attachment\_quartile\_2                  |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| attachment\_quartile\_3                  |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| attachment\_total\_view\_time\_millis    |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| attachment\_view\_completion             |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| avg\_screen\_time\_millis                |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| avg\_view\_time\_millis                  |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| impressions                              |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| ios\_installs                            |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| quartile\_1                              |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| quartile\_2                              |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| quartile\_3                              |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| screen\_time\_millis                     |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| spend                                    |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| coupon\_used\_local                      |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| coupon\_used\_usd                        |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| swipe\_up\_percent                       |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| swipes                                   |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| total\_installs                          |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| landing\_page\_views                     |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| video\_views                             |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| video\_views\_time\_based                |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| video\_views\_15s                        |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| view\_completion                         |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| view\_time\_millis                       |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| paid\_impressions                        |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| earned\_impressions                      |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| total\_impressions                       |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| play\_time\_millis                       |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| profile\_clicks                          |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| shares                                   |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| saves                                    |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| place\_opens                             |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| place\_actions                           |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| native\_leads                            |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_purchases                    |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_purchases\_value             |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_save                         |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_save\_value                  |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_start\_checkout              |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_start\_checkout\_value       |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_add\_cart                    |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_add\_cart\_value             |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_view\_content                |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_view\_content\_value         |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_add\_billing                 |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_add\_billing\_value          |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_signups                      |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_signups\_value               |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_searches                     |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_searches\_value              |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_level\_completes             |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_level\_completes\_value      |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_app\_opens                   |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_app\_opens\_value            |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_page\_views                  |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_page\_views\_value           |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_subscribe                    |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_subscribe\_value             |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_ad\_click                    |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_ad\_click\_value             |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_ad\_view                     |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_ad\_view\_value              |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_complete\_tutorial           |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_complete\_tutorial\_value    |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_invite                       |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_invite\_value                |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_login                        |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_login\_value                 |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_share                        |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_share\_value                 |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_reserve                      |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_reserve\_value               |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_achievement\_unlocked        |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_achievement\_unlocked\_value |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_add\_to\_wishlist            |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_add\_to\_wishlist\_value     |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_spend\_credits               |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_spend\_credits\_value        |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_rate                         |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_rate\_value                  |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_start\_trial                 |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_start\_trial\_value          |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_list\_view                   |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| conversion\_list\_view\_value            |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| custom\_event\_1                         |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| custom\_event\_1\_value                  |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| custom\_event\_2                         |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| custom\_event\_2\_value                  |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| custom\_event\_3                         |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| custom\_event\_3\_value                  |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| custom\_event\_4                         |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| custom\_event\_4\_value                  |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| custom\_event\_5                         |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| custom\_event\_5\_value                  |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| attachment\_frequency                    | YES       | NO                                                                          | YES                                                                         | YES. Available from 1st January 2021                                                                                                                          | YES                                              |
| attachment\_uniques                      |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| frequency                                |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| uniques                                  |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| total\_reach                             |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |
| earned\_reach                            |           |                                                                             |                                                                             |                                                                                                                                                               |                                                  |

## Example for All Metrics[​**](#example-for-all-metrics "Copy to clipboard")

```
curl -H "Authorization: Bearer meowmeow" \
    "https://adsapi.snapchat.com/v1/campaigns/2bbaa6e3-4ddb-4358-9efe-48334952f4aa/stats?breakdown=adsquad&fields=android_installs,avg_screen_time_millis,attachment_frequency,attachment_quartile_1,attachment_quartile_2,attachment_quartile_3,attachment_total_view_time_millis,attachment_uniques,attachment_view_completion,frequency,impressions,ios_installs,quartile_1,quartile_2,quartile_3,spend,swipe_up_percent,swipes,total_installs,uniques,view_completion,screen_time_millis&granularity=DAY&start_time=2016-10-24T07:00:00.000-00:00&end_time=2016-10-26T07:00:00.000-00:00"
```

```
{
  "request_status": "SUCCESS",
  "request_id": "5813ccf400ff07b016a837c09f0001737e616473617069736300016275696c642d65373832323966352d73746174732d322d7465737400010133",
  "timeseries_stats": [
    {
      "sub_request_status": "SUCCESS",
      "timeseries_stat": {
        "id": "2bbaa6e3-4ddb-4358-9efe-48334952f4aa",
        "type": "CAMPAIGN",
        "start_time": "2016-10-24T07:00:00.000Z",
        "end_time": "2016-10-26T07:00:00.000Z",
        "breakdown_stats": {
          "adsquad": [
            {
              "id": "134aeb99-6552-4f1d-b7a6-82b9813fd079",
              "type": "AD_SQUAD",
              "granularity": "DAY",
              "start_time": "2016-10-24T07:00:00.000Z",
              "end_time": "2016-10-26T07:00:00.000Z",
              "timeseries": [
                {
                  "start_time": "2016-10-24T07:00:00.000Z",
                  "end_time": "2016-10-25T07:00:00.000Z",
                  "stats": {
                    "impressions": 18294,
                    "swipes": 0,
                    "quartile_1": 7489,
                    "quartile_2": 2595,
                    "quartile_3": 1964,
                    "view_completion": 1635,
                    "attachment_quartile_1": 0,
                    "attachment_quartile_2": 0,
                    "attachment_quartile_3": 0,
                    "attachment_view_completion": 0,
                    "attachment_total_view_time_millis": 0,
                    "frequency": 1.0014,
                    "avg_screen_time_millis": 1832,
                    "swipe_up_percent": 0,
                    "attachment_frequency": 0,
                    "attachment_avg_view_time_millis": 0,
                    "uniques": 18268,
                    "attachment_uniques": 0,
                    "ios_installs": 0,
                    "android_installs": 0,
                    "total_installs": 0,
                    "spend": 144213617,
                    "screen_time_millis": 33876700
                  }
                },
                {
                  "start_time": "2016-10-25T07:00:00.000Z",
                  "end_time": "2016-10-26T07:00:00.000Z",
                  "stats": {
                    "impressions": 15377,
                    "swipes": 0,
                    "quartile_1": 6345,
                    "quartile_2": 2185,
                    "quartile_3": 1596,
                    "view_completion": 1324,
                    "attachment_quartile_1": 0,
                    "attachment_quartile_2": 0,
                    "attachment_quartile_3": 0,
                    "attachment_view_completion": 0,
                    "attachment_total_view_time_millis": 0,
                    "frequency": 1.0011,
                    "avg_screen_time_millis": 1828,
                    "swipe_up_percent": 0,
                    "attachment_frequency": 0,
                    "attachment_avg_view_time_millis": 0,
                    "uniques": 15360,
                    "attachment_uniques": 0,
                    "ios_installs": 0,
                    "android_installs": 0,
                    "total_installs": 0,
                    "spend": 120978178,
                    "screen_time_millis": 28547600
                  }
                }
              ]
            }
}
```

Show more▼

## Get Ad Account Stats[​**](#get-ad-account-stats "Copy to clipboard")

```
curl "https://adsapi.snapchat.com/v1/adaccounts/22335ba6-7558-4100-9663-baca7adff5f2/stats?granularity=TOTAL&fields=spend" \
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "success",
  "request_id": "57b24d9c00ff0d85622341e7c60001737e616473617069736300016275676c642b34326313636139312d332d31312d390001010d",
  "total_stats": [
    {
      "sub_request_status": "success",
      "total_stat": {
        "id": "22335ba6-7558-4100-9663-baca7adff5f2",
        "type": "AD_ACCOUNT",
        "granularity": "TOTAL",
        "stats": {
          "spend": 89196290
        },
        "finalized_data_end_time": "2019-08-29T03:00:00.000-07:00"
      }
    }
  ]
}
```

This endpoint retrieves the spend metric for the specified Ad Account, the spend metric is the only metric available for the ad account entity.

### HTTP Request[​**](#http-request-1 "Copy to clipboard")

`GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats`

### Parameters[​**](#parameters "Copy to clipboard")

| Parameter       | Default | Description   |
| --------------- | ------- | ------------- |
| ad\_account\_id |         | Ad Account ID |

## Get Campaign Stats[​**](#get-campaign-stats "Copy to clipboard")

```
curl "https://adsapi.snapchat.com/v1/campaigns/92e1c28a-a331-45b4-8c26-fd3e0eea8c39/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend" \
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "success",
  "request_id": "57b24d9c00ff0d85622341e7c60001737e616473617069736300016275696c642d34326333636139312d312d31312d390001010d",
  "total_stats": [
    {
      "sub_request_status": "success",
      "total_stat": {
        "id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
        "type": "CAMPAIGN",
        "granularity": "TOTAL",
        "stats": {
          "impressions": 0,
          "swipes": 0,
          "spend": 0,
          "quartile_1": 0,
          "quartile_2": 0,
          "quartile_3": 0,
          "view_completion": 0,
          "screen_time_millis": 0
        }
      }
    }
  ]
}
```

This endpoint retrieves stats for the specified Campaign.

### HTTP Request[​**](#http-request-2 "Copy to clipboard")

`GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/stats`

### Parameters[​**](#parameters-1 "Copy to clipboard")

| Parameter    | Default | Description |
| ------------ | ------- | ----------- |
| campaign\_id |         | Campaign ID |

## Get Ad Squad Stats[​**](#get-ad-squad-stats "Copy to clipboard")

```
curl "https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend"
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "success",
  "request_id": "57b24e5200ff0225cdf221e6c90001737e616473617069736300016275696c642d34326333636139312d312d31312d3900010106",
  "total_stats": [
    {
      "sub_request_status": "success",
      "total_stat": {
        "id": "23995202-bfbc-45a0-9702-dd6841af52fe",
        "type": "AD_SQUAD",
        "granularity": "TOTAL",
        "stats": {
          "impressions": 0,
          "swipes": 0,
          "spend": 0,
          "quartile_1": 0,
          "quartile_2": 0,
          "quartile_3": 0,
          "view_completion": 0,
          "screen_time_millis": 0
        }
      }
    }
  ]
}
```

This endpoint retrieves stats for the specified Ad Squad.

### HTTP Request[​**](#http-request-3 "Copy to clipboard")

`GET https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}/stats`

### Parameters[​**](#parameters-2 "Copy to clipboard")

| Parameter   | Default | Description |
| ----------- | ------- | ----------- |
| adsquad\_id |         | Ad Squad ID |

## Get Ad Stats[​**](#get-ad-stats "Copy to clipboard")

```
curl "https://adsapi.snapchat.com/v1/ads/e8d6217f-32ab-400f-9e54-39a86a7963e4/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend"
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "success",
  "request_id": "57b24ec400ff0b0a2104182f430001737e616473617069736300016275696c642d34326333636139312d312d31312d390001010f",
  "total_stats": [
    {
      "sub_request_status": "success",
      "total_stat": {
        "id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
        "type": "AD",
        "granularity": "TOTAL",
        "stats": {
          "impressions": 0,
          "swipes": 0,
          "spend": 0,
          "quartile_1": 0,
          "quartile_2": 0,
          "quartile_3": 0,
          "view_completion": 0,
          "screen_time_millis": 0
        }
      }
    }
  ]
}
```

This endpoint retrieves stats for the specified Ad.

### HTTP Request[​**](#http-request-4 "Copy to clipboard")

`GET https://adsapi.snapchat.com/v1/ads/{ad_id}/stats`

### Parameters[​**](#parameters-3 "Copy to clipboard")

| Parameter | Default | Description |
| --------- | ------- | ----------- |
| ad\_id    |         | Ad ID       |

## Reporting for Creatives and Media[​**](#reporting-for-creatives-and-media "Copy to clipboard")

It's possible to fetch reporting for the Creative entity and the Media entity given some restrictions.

* The available granularities for Media and Creative reporting are DAY and LIFETIME
* The TOTAL granularity is **not** available for Creatives and Media
* Reach metrics (frequency, attachment\_frequency, uniques, attachment\_uniques, total\_reach) are **not** available for Media and Creatives
* Reporting is only available to non-DPA Creatives

| Creative                | Type                                | Reporting availability |
| ----------------------- | ----------------------------------- | ---------------------- |
| Snap Ad                 | SNAP\_AD                            | Yes                    |
| Snap Ad with attachment | APP\_INSTALL, WEB\_VIEW, DEEP\_LINK | Yes                    |
| Collection              | COLLECTION                          | Yes                    |
| Composite (story)       | COMPOSITE                           | Yes                    |
| Preview Creative        | PREVIEW                             | No                     |

| Media            | Type          | Reporting availability |
| ---------------- | ------------- | ---------------------- |
| Top Snap         | IMAGE         | Yes                    |
| Top Snap         | VIDEO         | Yes                    |
| Lens LENS        | LENS\_PACKAGE | Yes                    |
| Story Tile       | IMAGE         | No                     |
| Creative element | IMAGE         | No                     |

## Fetching reporting for a Creative[​**](#fetching-reporting-for-a-creative "Copy to clipboard")

This endpoint retrieves stats for the specified Creative.

### HTTP Request[​**](#http-request-5 "Copy to clipboard")

`GET https://adsapi.snapchat.com/v1/creatives/{creative_id}/stats`

### Parameters[​**](#parameters-4 "Copy to clipboard")

| Parameter    | Default | Description |
| ------------ | ------- | ----------- |
| creative\_id |         | Creative ID |

### Example 1 - Fetching LIFETIME metrics for a Creative[​**](#example-1---fetching-lifetime-metrics-for-a-creative "Copy to clipboard")

```
curl "https://adsapi.snapchat.com/v1/creatives/c298f904-628f-45fb-9158-07c37bff78ef/stats?fields=swipes,impressions,conversion_sign_ups,engaged_views,video_views_5s&granularity=LIFETIME"
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "SUCCESS",
  "request_id": "0bfc1b98-39f7-46fe-bbab-2b829bce0aa6",
  "lifetime_stats": [
    {
      "sub_request_status": "SUCCESS",
      "lifetime_stat": {
        "id": "c298f904-628f-45fb-9158-07c37bff78ef",
        "type": "CREATIVE",
        "granularity": "LIFETIME",
        "stats": {
          "impressions": 3615,
          "swipes": 89,
          "engaged_views": 683,
          "video_views_5s": 722,
          "conversion_sign_ups": 1
        },
        "start_time": "2016-09-26T15:00:00.000+08:00",
        "end_time": "2025-06-17T21:00:00.000+08:00",
        "finalized_data_end_time": "2025-06-17T10:00:00.000Z",
        "conversion_data_processed_end_time": "2025-06-17T00:00:00.000Z"
      }
    }
  ]
}
```

### Example 2 - Fetching DAY metrics for a COMPOSITE Creative[​**](#example-2---fetching-day-metrics-for-a-composite-creative "Copy to clipboard")

```
curl "https://adsapi.snapchat.com/v1/creatives/7ef4ee2e-fdc1-412f-8d2f-098cd515af0c/stats?fields=swipes,impressions,conversion_page_views,engaged_views,video_views_5s&granularity=DAY&start_time=2025-05-16T00:00:00&end_time=2025-05-21T00:00:00"
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "SUCCESS",
  "request_id": "0da83efa-7c44-46b6-be6a-145c66752419",
  "timeseries_stats": [
    {
      "sub_request_status": "SUCCESS",
      "timeseries_stat": {
        "id": "7ef4ee2e-fdc1-412f-8d2f-098cd515af0c",
        "type": "CREATIVE",
        "granularity": "DAY",
        "start_time": "2025-05-16T00:00:00.000-07:00",
        "end_time": "2025-05-21T00:00:00.000-07:00",
        "finalized_data_end_time": "2025-06-17T10:00:00.000Z",
        "conversion_data_processed_end_time": "2025-06-17T00:00:00.000Z",
        "timeseries": [
          {
            "start_time": "2025-05-16T00:00:00.000-07:00",
            "end_time": "2025-05-17T00:00:00.000-07:00",
            "stats": {
              "impressions": 1243,
              "swipes": 26,
              "engaged_views": 148,
              "video_views_5s": 91,
              "conversion_page_views": 103
            }
          },
          {
            "start_time": "2025-05-17T00:00:00.000-07:00",
            "end_time": "2025-05-18T00:00:00.000-07:00",
            "stats": {
              "impressions": 761,
              "swipes": 25,
              "engaged_views": 100,
              "video_views_5s": 63,
              "conversion_page_views": 166
            }
          },
          {
            "start_time": "2025-05-18T00:00:00.000-07:00",
            "end_time": "2025-05-19T00:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "engaged_views": 0,
              "video_views_5s": 0,
              "conversion_page_views": 32
            }
          },
          {
            "start_time": "2025-05-19T00:00:00.000-07:00",
            "end_time": "2025-05-20T00:00:00.000-07:00",
            "stats": {
              "impressions": 181,
              "swipes": 1,
              "engaged_views": 8,
              "video_views_5s": 4,
              "conversion_page_views": 35
            }
          },
          {
            "start_time": "2025-05-20T00:00:00.000-07:00",
            "end_time": "2025-05-21T00:00:00.000-07:00",
            "stats": {
              "impressions": 838,
              "swipes": 14,
              "engaged_views": 41,
              "video_views_5s": 31,
              "conversion_page_views": 18
            }
          }
        ]
      }
    }
  ]
}
```

Show more▼

## Fetching reporting for a Media[​**](#fetching-reporting-for-a-media "Copy to clipboard")

This endpoint retrieves stats for the specified Media entity.

### HTTP Request[​**](#http-request-6 "Copy to clipboard")

`GET https://adsapi.snapchat.com/v1/media/{media_id}/stats`

### Parameters[​**](#parameters-5 "Copy to clipboard")

| Parameter | Default | Description |
| --------- | ------- | ----------- |
| media\_id |         | Media ID    |

### Example 1 - Fetching LIFETIME metrics for a VIDEO Media[​**](#example-1---fetching-lifetime-metrics-for-a-video-media "Copy to clipboard")

```
curl "https://adsapi.snapchat.com/v1/media/37706b9d-b682-40bd-b395-d9bc373ad344/stats?fields=swipes,impressions,spend,video_views,video_views_5s&granularity=LIFETIME"
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "SUCCESS",
  "request_id": "4faa5c90-6518-40df-a518-0ca5f0689439",
  "lifetime_stats": [
    {
      "sub_request_status": "SUCCESS",
      "lifetime_stat": {
        "id": "37706b9d-b682-40bd-b395-d9bc373ad344",
        "type": "MEDIA",
        "granularity": "LIFETIME",
        "stats": {
          "impressions": 87372,
          "swipes": 875,
          "spend": 924881119,
          "video_views": 3998,
          "video_views_5s": 2195
        },
        "start_time": "2016-09-26T00:00:00.000-07:00",
        "end_time": "2025-06-17T07:00:00.000-07:00",
        "finalized_data_end_time": "2025-06-17T10:00:00.000Z"
      }
    }
  ]
}
```

### Example 2 - Fetching DAY metrics for an IMAGE Media[​**](#example-2---fetching-day-metrics-for-an-image-media "Copy to clipboard")

```
curl "https://adsapi.snapchat.com/v1/media/24776771-820e-49f9-a12c-064ec26461ef/stats?granularity=DAY&start_time=2024-10-01T00:00:00&end_time=2024-10-04T00:00:00&fields=swipes,impressions,spend,video_views,video_views_5s"
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "SUCCESS",
  "request_id": "ccef25c1-f1aa-473a-b24c-df4841f11f02",
  "timeseries_stats": [
    {
      "sub_request_status": "SUCCESS",
      "timeseries_stat": {
        "id": "24776771-820e-49f9-a12c-064ec26461ef",
        "type": "MEDIA",
        "granularity": "DAY",
        "start_time": "2024-10-01T00:00:00.000-07:00",
        "end_time": "2024-10-04T00:00:00.000-07:00",
        "finalized_data_end_time": "2025-06-17T11:00:00.000Z",
        "timeseries": [
          {
            "start_time": "2024-10-01T00:00:00.000-07:00",
            "end_time": "2024-10-02T00:00:00.000-07:00",
            "stats": {
              "impressions": 52556,
              "swipes": 124,
              "spend": 146756413,
              "video_views": 0,
              "video_views_5s": 0
            }
          },
          {
            "start_time": "2024-10-02T00:00:00.000-07:00",
            "end_time": "2024-10-03T00:00:00.000-07:00",
            "stats": {
              "impressions": 102442,
              "swipes": 260,
              "spend": 338567764,
              "video_views": 0,
              "video_views_5s": 0
            }
          },
          {
            "start_time": "2024-10-03T00:00:00.000-07:00",
            "end_time": "2024-10-04T00:00:00.000-07:00",
            "stats": {
              "impressions": 55624,
              "swipes": 154,
              "spend": 204067975,
              "video_views": 0,
              "video_views_5s": 0
            }
          }
        ]
      }
    }
  ]
}
```

Show more▼

## Reporting Insights and Dimensions[​**](#reporting-insights-and-dimensions "Copy to clipboard")

Delivery Insights can help you understand who viewed, engaged, and took action on your ads. These insights across demographic, location, device, and interest categories can help inform optimization and increase overall campaign efficiency. Insights can be pulled for specific campaigns, ad squads, or ads; insights can also use breakdowns for multiple campaigns, ad squads, or ads at once.

* Delivery Insights are estimated to protect user privacy. They are meant to provide directional guidance on audience performance.
* Delivery Insights are only availble on days when there are at least 30 impressions.
* Delivery Insights are only available from 1 January 2020. DAY, TOTAL, and LIFETIME granularities are supported, the HOUR granularity is not available for delivery insights. Some conversion reporting metrics are available from 1 May 2020.
* Delivery insights for the combination of Country and Operating System are available from 24 October 2022 onwards.

### Dimensions[​**](#dimensions "Copy to clipboard")

You can get reporting insights based on different geographic, demographic, interest-based, and device-based dimensions. You can only query one dimension at a time unless you are querying age & gender which may be combined. Some of the dimensions (region/dma/make) only support Delivery metrics, for these dimensions it's not possible to fetch conversion metrics.

Using the report\_dimension query string parameter you can see Snapchat metrics based on a number of new dimensions

| Category    | API Dimension (report\_dimension) | Conditions                                                             | Metrics availability |
| ----------- | --------------------------------- | ---------------------------------------------------------------------- | -------------------- |
| Geo         | country                           | Metrics broken down by ISO country code                                | Delivery/Conversion  |
|             | country,os\*                      | Metrics broken down by ISO country code and Device Operating System\*  | Delivery             |
|             | region                            | Metrics broken down by region                                          | Delivery             |
|             | dma                               | Metrics broken down by dma                                             | Delivery             |
| Demographic | gender                            | Metrics broken down by gender                                          | Delivery/Conversion  |
|             | age\*\*                           | Metrics broken down by age buckets\*\*                                 | Delivery/Conversion  |
|             | age,gender                        | Metrics broken down by age and gender                                  | Delivery/Conversion  |
| Device      | os                                | Device Operating System                                                | Delivery/Conversion  |
|             | os,country                        | Metrics broken down by Device Operating System and ISO country code\*  | Delivery             |
|             | make                              | Device Make                                                            | Delivery             |
| Interest    | lifestyle\_category               | Metrics broken down by interest category (Snapchat Lifestyle Category) | Delivery             |

\*Country/OS metrics breakdown is available from 24 October 2022

\*\*Age bucket breakdown have been expanded since 28 February 2025

### Metrics[​**](#metrics "Copy to clipboard")

You may pass these metrics as a comma separated list for the `fields` query parameter. Conversion metrics support attribution windows, swipe/view variants, and value metrics in local microcents. Note that conversion metrics are not available for the dimensions `lifestyle_category`, `region`,`dma` or `make`.

### Delivery Metrics[​**](#delivery-metrics "Copy to clipboard")

| Metric                  | API field                             | Description                                                                                                                                                       |
| ----------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Paid Impressions        | impressions                           | Impression Count                                                                                                                                                  |
| Unique Impressions      | uniques                               | Unique Impressions Count                                                                                                                                          |
| Swipe Ups               | swipes                                | Swipe-Up Count                                                                                                                                                    |
| 25% Quartile            | quartile\_1                           | Video Views to 25%                                                                                                                                                |
| 50% Quartile            | quartile\_2                           | Video Views to 50%                                                                                                                                                |
| 75% Quartile            | quartile\_3                           | Video Views to 75%                                                                                                                                                |
| Completions             | view\_completion                      | Video Views to completion                                                                                                                                         |
| Spend                   | spend                                 | Amount Spent (micro-currency)                                                                                                                                     |
| Video Views             | video\_views                          | The total number of impressions that meet the qualifying video view criteria of at least 2 seconds of consecutive watch time or a swipe up action on the Top Snap |
| Engaged views\*         | engaged\_views                        | The total number of times Snapchatters viewed your video ad for five seconds or longer                                                                            |
| Landing Page Views\*\*  | landing\_page\_views\*                | The total number of times a user loaded the ad’s landing page after a click                                                                                       |
| Attachment Uniques      | attachment\_uniques                   | Attachment Uniques                                                                                                                                                |
| 25% Attachment Quartile | attachment\_quartile\_1               | Long Form Video Views to 25%                                                                                                                                      |
| 50% Attachment Quartile | attachment\_quartile\_2               | Long Form Video Views to 50%                                                                                                                                      |
| 75% Attachment Quartile | attachment\_quartile\_3               | Long Form Video Views to 75%                                                                                                                                      |
| Attachment Completions  | attachment\_view\_completion          | Long Form Video Views to completion                                                                                                                               |
| Attachment View Time    | attachment\_total\_view\_time\_millis | Total Attachment View Time (milli-seconds)                                                                                                                        |
| Attachment Video Views  | attachment\_video\_views              | Long Form Video Attachment Views                                                                                                                                  |
| Story Opens             | story\_opens                          | # of times users tapped on the ad tile in the feed to view the Story Ad                                                                                           |
| Story Completes         | story\_completes                      | # of times users viewed through to the last Snap of your Story Ad                                                                                                 |
| Shares                  | shares                                | # of times lens/filter was shared in a Chat or Story                                                                                                              |
| Saves                   | saves                                 | # of times lens/filter was saved to Memories                                                                                                                      |
| Place Opens             | place\_opens                          | # of times users tapped the Promoted Place Profile                                                                                                                |
| Place Actions           | place\_actions                        | # of actions taken in Promoted Place Profile                                                                                                                      |

\*engaged\_views are available from 10 February 2025

\*\*landing\_page\_views are available from 10 December 2024

### Conversion Metrics[​**](#conversion-metrics "Copy to clipboard")

| Metric                | API field                         | Description                                                                                   |
| --------------------- | --------------------------------- | --------------------------------------------------------------------------------------------- |
| Installs              | total\_installs                   | Total # of App Installs                                                                       |
| Purchases             | conversion\_purchases             | # of attributed “PURCHASE” conversion events\*\*                                              |
| Purchase Value        | conversion\_purchases\_value      | Value of attributed “PURCHASE” conversion events (microcurrency in Ad Account’s currency)\*\* |
| Saves                 | conversion\_save                  | # of attributed “SAVE” conversion events\*\*                                                  |
| Start Checkout        | conversion\_start\_checkout       | # of attributed “START\_CHECKOUT” conversion events\*\*                                       |
| Add To Cart           | conversion\_add\_cart             | # of attributed “ADD\_CART” conversion events\*\*                                             |
| View Content          | conversion\_view\_content         | # of attributed “VIEW\_CONTENT” conversion events\*\*                                         |
| Add Billing           | conversion\_add\_billing          | # of attributed “ADD\_BILLING” conversion events\*\*                                          |
| Sign Ups              | conversion\_sign\_ups             | # of attributed “SIGN\_UP” conversion events\*\*                                              |
| Searches              | conversion\_searches              | # of attributed “SEARCH” conversion events\*\*                                                |
| Level Completes       | conversion\_level\_completes      | # of attributed “LEVEL\_COMPLETE” conversion events\*\*                                       |
| App Opens             | conversion\_app\_opens            | # of attributed “APP\_OPEN” conversion events\*\*                                             |
| Page Views            | conversion\_page\_views           | # of attributed “PAGE\_VIEW” conversion events\*\*                                            |
| Subscribes            | conversion\_subscribe             | # of attributed "SUBSCRIBE" conversion events++                                               |
| Ad Clicks             | conversion\_ad\_click             | # of attributed “CONVERSION\_AD\_CLICK” conversion events++                                   |
| Ad Views              | conversion\_ad\_view              | # of attributed “CONVERSION\_AD\_VIEW” conversion events++                                    |
| Completed Tutorials   | conversion\_complete\_tutorial    | # of attributed “CONVERSION\_COMPLETE\_TUTORIAL” conversion events++                          |
| Invites Sent          | conversion\_invite                | # of attributed “CONVERSION\_INVITE” conversion events++                                      |
| Logins                | conversion\_login                 | # of attributed “CONVERSION\_LOGIN” conversion events++                                       |
| Shares                | conversion\_share                 | # of attributed “CONVERSION\_SHARE” conversion events++                                       |
| Reservations          | conversion\_reserve               | # of attributed “CONVERSION\_RESERVE” conversion events++                                     |
| Achievements Unlocked | conversion\_achievement\_unlocked | # of attributed “CONVERSION\_ACHIEVEMENT\_UNLOCKED” conversion events++                       |
| Adds to Wishlist      | conversion\_add\_to\_wishlist     | # of attributed “CONVERSION\_ADD\_TO\_WISHLIST” conversion events++                           |
| Credits Spent         | conversion\_spend\_credits        | # of attributed “CONVERSION\_SPEND\_CREDITS” conversion events++                              |
| Rates Submitted       | conversion\_rate                  | # of attributed “CONVERSION\_RATE” conversion events++                                        |
| Trial Starts          | conversion\_start\_trial          | # of attributed “CONVERSION\_START\_TRIAL” conversion events++                                |
| Lists Viewed          | conversion\_list\_view            | # of attributed “LIST\_VIEW” conversion events++                                              |
| Store Visits          | conversion\_visit                 | # of attributed “VISIT” conversion events++                                                   |
| Custom Event 1        | custom\_event\_1                  | # of attributed “CUSTOM\_EVENT\_1” conversion events++                                        |
| Custom Event 2        | custom\_event\_2                  | # of attributed “CUSTOM\_EVENT\_2” conversion events++                                        |
| Custom Event 3        | custom\_event\_3                  | # of attributed “CUSTOM\_EVENT\_3” conversion events++                                        |
| Custom Event 4        | custom\_event\_4                  | # of attributed “CUSTOM\_EVENT\_4” conversion events++                                        |
| Custom Event 5        | custom\_event\_5                  | # of attributed “CUSTOM\_EVENT\_5” conversion events++                                        |

\*\* This conversion metric is available from 1st January 2020 when using **action\_report\_time=conversion** and 1st May 2020 when using \*\*action\_report\_time=impression\*\*

++ This conversion metric is available from 1st of May 2020 for both **action\_report\_time=conversion** and **action\_report\_time=impression**

## Insights by GEO[​**](#insights-by-geo "Copy to clipboard")

### HTTP Request[​**](#http-request-7 "Copy to clipboard")

`GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats`

### Parameters[​**](#parameters-6 "Copy to clipboard")

| Parameter         | Possible values    | Description                  |
| ----------------- | ------------------ | ---------------------------- |
| ad\_account\_id   |                    | Ad Account ID                |
| report\_dimension | country,region,dma | The desired Report Dimension |

### Example of Geographic Insights[​**](#example-of-geographic-insights "Copy to clipboard")

This retrieves insights for country broken down to Campaign level using `report_dimension=country`.

```
curl "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/stats/?granularity=TOTAL&breakdown=campaign&fields=impressions,swipes,conversion_purchases&report_dimension=country&start_time=2020-01-25T00:00:00-08:00&end_time=2020-01-26T00:00:00-08:00&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY"
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "SUCCESS",
  "request_id": "5e6bee5400ff0aaf11217b24900001737e616473617069736300016275696c642d31636430373832652d312d3333342d3000010128",
  "total_stats": [
    {
      "sub_request_status": "SUCCESS",
      "total_stat": {
        "id": "22225ba6-7559-4000-9663-bace8adff5f2",
        "type": "AD_ACCOUNT",
        "granularity": "TOTAL",
        "swipe_up_attribution_window": "28_DAY",
        "view_attribution_window": "1_DAY",
        "start_time": "2020-01-25T00:00:00.000-08:00",
        "end_time": "2020-01-26T00:00:00.000-08:00",
        "finalized_data_end_time": "2020-03-13T00:00:00.000-07:00",
        "breakdown_stats": {
          "campaign": [
            {
              "id": "88821981-14be-4315-9832-278b27004d68",
              "type": "CAMPAIGN",
              "granularity": "TOTAL",
              "start_time": "2020-01-25T00:00:00.000-08:00",
              "end_time": "2020-01-26T00:00:00.000-08:00",
              "dimension_stats": [
                {
                  "impressions": 23433,
                  "swipes": 141,
                  "country": "au",
                  "conversion_purchases": 3
                }
              ]
            },
            {
              "id": "8079bbff-8a7b-4548-8556-d726461da248",
              "type": "CAMPAIGN",
              "granularity": "TOTAL",
              "start_time": "2020-01-25T00:00:00.000-08:00",
              "end_time": "2020-01-26T00:00:00.000-08:00",
              "dimension_stats": [
                {
                  "impressions": 19970,
                  "swipes": 488,
                  "country": "us",
                  "conversion_purchases": 4
                }
              ]
            },
            {
              "id": "828f739c-7f32-4013-9a92-58c6495e9438",
              "type": "CAMPAIGN",
              "granularity": "TOTAL",
              "start_time": "2020-01-25T00:00:00.000-08:00",
              "end_time": "2020-01-26T00:00:00.000-08:00",
              "dimension_stats": [
                {
                  "impressions": 46068,
                  "swipes": 74,
                  "country": "fr",
                  "conversion_purchases": 5
                }
              ]
            }
          ]
        },
        "split_results": []
      }
    }
  ]
}
```

Show more▼

## Insights by DEMO[​**](#insights-by-demo "Copy to clipboard")

When requesting reporting insights using demographic parameters (age/gender) the response will be broken into age buckets.

Following the introduction of the possibility to target Snapchat users aged 55+ in February 2025 we have introduced additional age buckets, this means the age buckets returned in reporting depends on the date that the campaign was live. Campaigns that ran prior to to 28 February 2025 only have a specific set of Age buckets available.

The 35+ age\_bucket will be deprecated on the **15 October 2026**, this means that the bucket won't appear in API requests querying for metrics beyond 15 October 2026.

The 35+ age bucket remains available for dates before the 15 October 2026 but we do not recommend it's use beyond the **28 February 2026** when the age bucket range was extended.

| Age buckets (age\_bucket) | Age buckets (age\_bucket) after 28 February 2025 | Description                                       |
| ------------------------- | ------------------------------------------------ | ------------------------------------------------- |
| 13-17                     | 13-17                                            |                                                   |
| 18-20                     | 18-20                                            |                                                   |
| 21-24                     | 21-24                                            |                                                   |
| 25-34                     | 25-34                                            |                                                   |
| 35+                       | 35+\*\*                                          | This bucket will start to return 0 from Day Month |
|                           | 35-44\*                                          | New age bucket                                    |
|                           | 45-54\*                                          | New age bucket                                    |
|                           | 55+\*                                            | New age bucket                                    |

\* These age buckets will start to account for conversion metrics from the 27 March 2025

\*\* The 35+ age bucket breakdown is due for deprecation on the 15 Octover 2026

### HTTP Request[​**](#http-request-8 "Copy to clipboard")

`GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats`

### Parameters[​**](#parameters-7 "Copy to clipboard")

| Parameter         | Possible values | Description                  |
| ----------------- | --------------- | ---------------------------- |
| ad\_account\_id   |                 | Ad Account ID                |
| report\_dimension | age,gender      | The desired Report Dimension |

### Example of Demographic Insights[​**](#example-of-demographic-insights "Copy to clipboard")

```
curl "https://adsapi.snapchat.com/v1/ads/a08f3e23-735b-4cd2-b72d-0cdb4d47967b/stats?granularity=TOTAL&fields=impressions,spend,swipe_up_percent,swipes,view_completion,conversion_sign_ups&start_time=2025-02-15&end_time=2025-03-05&report_dimension=age,gender"
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "SUCCESS",
  "request_id": "0126c186-4416-4dea-8be0-2a999b54c780",
  "total_stats": [
    {
      "sub_request_status": "SUCCESS",
      "total_stat": {
        "id": "a08f3e23-735b-4cd2-b72d-0cdb4d47967b",
        "type": "AD",
        "granularity": "TOTAL",
        "swipe_up_attribution_window": "28_DAY",
        "view_attribution_window": "1_DAY",
        "engaged_view_attribution_window": "2_DAY",
        "start_time": "2025-02-15T00:00:00.000-05:00",
        "end_time": "2025-03-05T00:00:00.000-05:00",
        "finalized_data_end_time": "2025-03-05T13:00:00.000Z",
        "conversion_data_processed_end_time": "2025-03-05T00:00:00.000Z",
        "dimension_stats": [
          {
            "impressions": 17461,
            "swipes": 16,
            "view_completion": 90,
            "swipe_up_percent": 0.0027,
            "spend": 362083431,
            "age_bucket": "13-17",
            "gender": "female",
            "conversion_sign_ups": 11
          },
          {
            "impressions": 12480,
            "swipes": 26,
            "view_completion": 59,
            "swipe_up_percent": 0.0019,
            "spend": 62093431,
            "age_bucket": "13-17",
            "gender": "male",
            "conversion_sign_ups": 22
          },
          {
            "impressions": 15461,
            "swipes": 26,
            "view_completion": 80,
            "swipe_up_percent": 0.0017,
            "spend": 262083431,
            "age_bucket": "25-34",
            "gender": "female",
            "conversion_sign_ups": 11
          },
          {
            "impressions": 2489,
            "swipes": 3,
            "view_completion": 10,
            "swipe_up_percent": 0.0012,
            "spend": 51786604,
            "age_bucket": "35-44",
            "gender": "female",
            "conversion_sign_ups": 0
          },
          {
            "impressions": 3379,
            "swipes": 7,
            "view_completion": 12,
            "swipe_up_percent": 0.0021,
            "spend": 70961784,
            "age_bucket": "35+",
            "gender": "female",
            "conversion_sign_ups": 2
          },
          {
            "impressions": 677,
            "swipes": 1,
            "view_completion": 2,
            "swipe_up_percent": 0.0015,
            "spend": 12764108,
            "age_bucket": "45-54",
            "gender": "female",
            "conversion_sign_ups": 0
          },
          {
            "impressions": 213,
            "swipes": 3,
            "view_completion": 0,
            "swipe_up_percent": 0.0141,
            "spend": 6410980,
            "age_bucket": "55+",
            "gender": "female",
            "conversion_sign_ups": 0
          },
          {
            "impressions": 2381,
            "swipes": 6,
            "view_completion": 6,
            "swipe_up_percent": 0.0025,
            "spend": 43242099,
            "age_bucket": "35-44",
            "gender": "male",
            "conversion_sign_ups": 0
          },
          {
            "impressions": 48007,
            "swipes": 82,
            "view_completion": 176,
            "swipe_up_percent": 0.0017,
            "spend": 536629398,
            "age_bucket": "18-20",
            "gender": "male",
            "conversion_sign_ups": 8
          },
          {
            "impressions": 35379,
            "swipes": 59,
            "view_completion": 116,
            "swipe_up_percent": 0.0017,
            "spend": 464316698,
            "age_bucket": "21-24",
            "gender": "male",
            "conversion_sign_ups": 10
          },
          {
            "impressions": 16760,
            "swipes": 18,
            "view_completion": 44,
            "swipe_up_percent": 0.0011,
            "spend": 270528840,
            "age_bucket": "25-34",
            "gender": "male",
            "conversion_sign_ups": 3
          },
          {
            "impressions": 3201,
            "swipes": 8,
            "view_completion": 9,
            "swipe_up_percent": 0.0025,
            "spend": 59504925,
            "age_bucket": "35+",
            "gender": "male",
            "conversion_sign_ups": 2
          },
          {
            "impressions": 60964,
            "swipes": 85,
            "view_completion": 177,
            "swipe_up_percent": 0.0014,
            "spend": 696182537,
            "age_bucket": "18-20",
            "gender": "female",
            "conversion_sign_ups": 22
          },
          {
            "impressions": 595,
            "swipes": 2,
            "view_completion": 1,
            "swipe_up_percent": 0.0034,
            "spend": 11822674,
            "age_bucket": "45-54",
            "gender": "male",
            "conversion_sign_ups": 0
          },
          {
            "impressions": 46007,
            "swipes": 58,
            "view_completion": 104,
            "swipe_up_percent": 0.0013,
            "spend": 583008613,
            "age_bucket": "21-24",
            "gender": "female",
            "conversion_sign_ups": 12
          },
          {
            "impressions": 225,
            "swipes": 0,
            "view_completion": 2,
            "swipe_up_percent": 0.0,
            "spend": 4440022,
            "age_bucket": "55+",
            "gender": "male",
            "conversion_sign_ups": 0
          }
        ]
      }
    }
  ]
}
```

Show more▼

This API requests retrieves insights for an Ad, broken down by age and gender by using the parameter `report_dimension=gender,age`.

## Reporting Insights: Dimension and Pivots[​**](#reporting-insights-dimension-and-pivots "Copy to clipboard")

On the 20th of March 2020 we announced the deprecation of the `dimension` and `pivots` parameters, please ensure that you have switched to using `report_dimension` by the 20th of June 2020. After the deprecation you will still be able to use `dimension` and `pivots` to retrieve data finalized prior to the 20th June 2020.

The new parameter `report_dimension` is described in the section below.

### Dimension and Pivots[​**](#dimension-and-pivots "Copy to clipboard")

You can get reporting insights based on different dimensions like GEO, DEMO, INTEREST and DEVICE by using the parameters `dimension` and `pivots`. Within each dimension, data can be broken down by different pivots. You can only query one dimension at a time. For insights breakdown, only LIFETIME granularity is supported.

| Dimension | Pivot                    | Required/Optional | Conditions                                                                     |
| --------- | ------------------------ | ----------------- | ------------------------------------------------------------------------------ |
| GEO       | country                  | Yes               | None                                                                           |
|           | region                   | No                | dma has to be queried with region                                              |
|           | dma                      | No                | dma has to be queried with region                                              |
| DEMO      | gender                   | No                | At least one of gender or age\_bucket has to be specified if dimension is DEMO |
|           | age\_bucket              | No                | At least one of gender or age\_bucket has to be specified if dimension is DEMO |
| INTEREST  | interest\_category\_id   | Yes               | None                                                                           |
|           | interest\_category\_name | No                | None                                                                           |
| DEVICE    | operating\_system        | Yes               | None                                                                           |
|           | make                     | No                | model has to be queried with make                                              |
|           | model                    | No                | model has to be queried with make                                              |

The fields that can be broken down by dimenssion and pivots are:

| Field                   | Description                                                |
| ----------------------- | ---------------------------------------------------------- |
| impressions             | Impression Count                                           |
| impression\_composition | The percent of impressions served to the insights category |
| uniques                 | # of unique impressions                                    |
| unique\_composition     | The percent of uniques served to the insights category     |
| spend                   | Amount spent (microcurrency)                               |
| swipes                  | Swipe up Count                                             |

## Attribution windows[​**](#attribution-windows "Copy to clipboard")

The attribution window is the time period in which a conversion will be counted after a user sees an ad. By default, Snap's attribution windows are 28 days post-swipe, 2 day post-view for engaged views (5 seconds or longer) and 1 day post-view (views shorter than 5 seconds).

### Metrics and their variants[​**](#metrics-and-their-variants "Copy to clipboard")

Conversions can be broken down by the method by which they were attributed, this table outlines the variant name that should be used in reporting requests.

| Metric                                   | Swipe variant                                       | Engaged View variant                                    | View variant                                   |
| ---------------------------------------- | --------------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------- |
| total\_installs                          | total\_installs\_swipe\_up                          | total\_installs\_engaged\_view                          | total\_installs\_view                          |
| total\_installs\_value                   | total\_installs\_value\_swipe\_up                   | total\_installs\_value\_engaged\_view                   | total\_installs\_value\_view                   |
| android\_installs                        | android\_installs\_swipe\_up                        | android\_installs\_engaged\_view                        | android\_installs\_view                        |
| android\_installs\_value                 | android\_installs\_value\_swipe\_up                 | android\_installs\_value\_engaged\_view                 | android\_installs\_value\_view                 |
| ios\_installs                            | ios\_installs\_swipe\_up                            | ios\_installs\_engaged\_view                            | ios\_installs\_view                            |
| ios\_installs\_value                     | ios\_installs\_value\_swipe\_up                     | ios\_installs\_value\_engaged\_view                     | ios\_installs\_value\_view                     |
| conversion\_purchases                    | conversion\_purchases\_swipe\_up                    | conversion\_purchases\_engaged\_view                    | conversion\_purchases\_view                    |
| conversion\_purchases\_value             | conversion\_purchases\_value\_swipe\_up             | conversion\_purchases\_value\_engaged\_view             | conversion\_purchases\_value\_view             |
| conversion\_save                         | conversion\_save\_swipe\_up                         | conversion\_save\_engaged\_view                         | conversion\_save\_view                         |
| conversion\_save\_value                  | conversion\_save\_value\_swipe\_up                  | conversion\_save\_value\_engaged\_view                  | conversion\_save\_value\_view                  |
| conversion\_start\_checkout              | conversion\_start\_checkout\_swipe\_up              | conversion\_start\_checkout\_engaged\_view              | conversion\_start\_checkout\_view              |
| conversion\_start\_checkout\_value       | conversion\_start\_checkout\_value\_swipe\_up       | conversion\_start\_checkout\_value\_engaged\_view       | conversion\_start\_checkout\_value\_view       |
| conversion\_add\_cart                    | conversion\_add\_cart\_swipe\_up                    | conversion\_add\_cart\_engaged\_view                    | conversion\_add\_cart\_view                    |
| conversion\_add\_cart\_value             | conversion\_add\_cart\_value\_swipe\_up             | conversion\_add\_cart\_value\_engaged\_view             | conversion\_add\_cart\_value\_view             |
| conversion\_view\_content                | conversion\_view\_content\_swipe\_up                | conversion\_view\_content\_engaged\_view                | conversion\_view\_content\_view                |
| conversion\_view\_content\_value         | conversion\_view\_content\_value\_swipe\_up         | conversion\_view\_content\_value\_engaged\_view         | conversion\_view\_content\_value\_view         |
| conversion\_add\_billing                 | conversion\_add\_billing\_swipe\_up                 | conversion\_add\_billing\_engaged\_view                 | conversion\_add\_billing\_view                 |
| conversion\_add\_billing\_value          | conversion\_add\_billing\_value\_swipe\_up          | conversion\_add\_billing\_value\_engaged\_view          | conversion\_add\_billing\_value\_view          |
| conversion\_sign\_ups                    | conversion\_sign\_ups\_swipe\_up                    | conversion\_sign\_ups\_engaged\_view                    | conversion\_sign\_ups\_view                    |
| conversion\_sign\_ups\_value             | conversion\_sign\_ups\_value\_swipe\_up             | conversion\_sign\_ups\_value\_engaged\_view             | conversion\_sign\_ups\_value\_view             |
| conversion\_searches                     | conversion\_searches\_swipe\_up                     | conversion\_searches\_engaged\_view                     | conversion\_searches\_view                     |
| conversion\_searches\_value              | conversion\_searches\_value\_swipe\_up              | conversion\_searches\_value\_engaged\_view              | conversion\_searches\_value\_view              |
| conversion\_level\_completes             | conversion\_level\_completes\_swipe\_up             | conversion\_level\_completes\_engaged\_view             | conversion\_level\_completes\_view             |
| conversion\_level\_completes\_value      | conversion\_level\_completes\_value\_swipe\_up      | conversion\_level\_completes\_value\_engaged\_view      | conversion\_level\_completes\_value\_view      |
| conversion\_app\_opens                   | conversion\_app\_opens\_swipe\_up                   | conversion\_app\_opens\_engaged\_view                   | conversion\_app\_opens\_view                   |
| conversion\_app\_opens\_value            | conversion\_app\_opens\_value\_swipe\_up            | conversion\_app\_opens\_value\_engaged\_view            | conversion\_app\_opens\_value\_view            |
| conversion\_page\_views                  | conversion\_page\_views\_swipe\_up                  | conversion\_page\_views\_engaged\_view                  | conversion\_page\_views\_view                  |
| conversion\_page\_views\_value           | conversion\_page\_views\_value\_swipe\_up           | conversion\_page\_views\_value\_engaged\_view           | conversion\_page\_views\_value\_view           |
| conversion\_subscribe                    | conversion\_subscribe\_swipe\_up                    | conversion\_subscribe\_engaged\_view                    | conversion\_subscribe\_view                    |
| conversion\_subscribe\_value             | conversion\_subscribe\_value\_swipe\_up             | conversion\_subscribe\_value\_engaged\_view             | conversion\_subscribe\_value\_view             |
| conversion\_ad\_click                    | conversion\_ad\_click\_swipe\_up                    | conversion\_ad\_click\_engaged\_view                    | conversion\_ad\_click\_view                    |
| conversion\_ad\_click\_value             | conversion\_ad\_click\_value\_swipe\_up             | conversion\_ad\_click\_value\_engaged\_view             | conversion\_ad\_click\_value\_view             |
| conversion\_ad\_view                     | conversion\_ad\_view\_swipe\_up                     | conversion\_ad\_view\_engaged\_view                     | conversion\_ad\_view\_view                     |
| conversion\_ad\_view\_value              | conversion\_ad\_view\_value\_swipe\_up              | conversion\_ad\_view\_value\_engaged\_view              | conversion\_ad\_view\_value\_view              |
| conversion\_complete\_tutorial           | conversion\_complete\_tutorial\_swipe\_up           | conversion\_complete\_tutorial\_engaged\_view           | conversion\_complete\_tutorial\_view           |
| conversion\_complete\_tutorial\_value    | conversion\_complete\_tutorial\_value\_swipe\_up    | conversion\_complete\_tutorial\_value\_engaged\_view    | conversion\_complete\_tutorial\_value\_view    |
| conversion\_invite                       | conversion\_invite\_swipe\_up                       | conversion\_invite\_engaged\_view                       | conversion\_invite\_view                       |
| conversion\_invite\_value                | conversion\_invite\_value\_swipe\_up                | conversion\_invite\_value\_engaged\_view                | conversion\_invite\_value\_view                |
| conversion\_login                        | conversion\_login\_swipe\_up                        | conversion\_login\_engaged\_view                        | conversion\_login\_view                        |
| conversion\_login\_value                 | conversion\_login\_value\_swipe\_up                 | conversion\_login\_value\_engaged\_view                 | conversion\_login\_value\_view                 |
| conversion\_share                        | conversion\_share\_swipe\_up                        | conversion\_share\_engaged\_view                        | conversion\_share\_view                        |
| conversion\_share\_value                 | conversion\_share\_value\_swipe\_up                 | conversion\_share\_value\_engaged\_view                 | conversion\_share\_value\_view                 |
| conversion\_reserve                      | conversion\_reserve\_swipe\_up                      | conversion\_reserve\_engaged\_view                      | conversion\_reserve\_view                      |
| conversion\_reserve\_value               | conversion\_reserve\_value\_swipe\_up               | conversion\_reserve\_value\_engaged\_view               | conversion\_reserve\_value\_view               |
| conversion\_achievement\_unlocked        | conversion\_achievement\_unlocked\_swipe\_up        | conversion\_achievement\_unlocked\_engaged\_view        | conversion\_achievement\_unlocked\_view        |
| conversion\_achievement\_unlocked\_value | conversion\_achievement\_unlocked\_value\_swipe\_up | conversion\_achievement\_unlocked\_value\_engaged\_view | conversion\_achievement\_unlocked\_value\_view |
| conversion\_add\_to\_wishlist            | conversion\_add\_to\_wishlist\_swipe\_up            | conversion\_add\_to\_wishlist\_engaged\_view            | conversion\_add\_to\_wishlist\_view            |
| conversion\_add\_to\_wishlist\_value     | conversion\_add\_to\_wishlist\_value\_swipe\_up     | conversion\_add\_to\_wishlist\_value\_engaged\_view     | conversion\_add\_to\_wishlist\_value\_view     |
| conversion\_spend\_credits               | conversion\_spend\_credits\_swipe\_up               | conversion\_spend\_credits\_engaged\_view               | conversion\_spend\_credits\_view               |
| conversion\_spend\_credits\_value        | conversion\_spend\_credits\_value\_swipe\_up        | conversion\_spend\_credits\_value\_engaged\_view        | conversion\_spend\_credits\_value\_view        |
| conversion\_rate                         | conversion\_rate\_swipe\_up                         | conversion\_rate\_engaged\_view                         | conversion\_rate\_view                         |
| conversion\_rate\_value                  | conversion\_rate\_value\_swipe\_up                  | conversion\_rate\_value\_engaged\_view                  | conversion\_rate\_value\_view                  |
| conversion\_start\_trial                 | conversion\_start\_trial\_swipe\_up                 | conversion\_start\_trial\_engaged\_view                 | conversion\_start\_trial\_view                 |
| conversion\_start\_trial\_value          | conversion\_start\_trial\_value\_swipe\_up          | conversion\_start\_trial\_value\_engaged\_view          | conversion\_start\_trial\_value\_view          |
| conversion\_list\_view                   | conversion\_list\_view\_swipe\_up                   | conversion\_list\_view\_engaged\_view                   | conversion\_list\_view\_view                   |
| conversion\_list\_view\_value            | conversion\_list\_view\_value\_swipe\_up            | conversion\_list\_view\_value\_engaged\_view            | conversion\_list\_view\_value\_view            |
| custom\_event\_1                         | custom\_event\_1\_swipe\_up                         | custom\_event\_1\_engaged\_view                         | custom\_event\_1\_view                         |
| custom\_event\_1\_value                  | custom\_event\_value\_swipe\_up                     | custom\_event\_value\_engaged\_view                     | custom\_event\_value\_view                     |
| custom\_event\_2                         | custom\_event\_2\_swipe\_up                         | custom\_event\_2\_engaged\_view                         | custom\_event\_2\_view                         |
| custom\_event\_2\_value                  | custom\_event\_value\_swipe\_up                     | custom\_event\_value\_engaged\_view                     | custom\_event\_value\_view                     |
| custom\_event\_3                         | custom\_event\_3\_swipe\_up                         | custom\_event\_3\_engaged\_view                         | custom\_event\_3\_view                         |
| custom\_event\_3\_value                  | custom\_event\_value\_swipe\_up                     | custom\_event\_value\_engaged\_view                     | custom\_event\_value\_view                     |
| custom\_event\_4                         | custom\_event\_4\_swipe\_up                         | custom\_event\_4\_engaged\_view                         | custom\_event\_4\_view                         |
| custom\_event\_4\_value                  | custom\_event\_4\_value\_swipe\_up                  | custom\_event\_4\_value\_engaged\_view                  | custom\_event\_4\_value\_view                  |
| custom\_event\_5                         | custom\_event\_5\_swipe\_up                         | custom\_event\_5\_engaged\_view                         | custom\_event\_5\_view                         |
| custom\_event\_5\_value                  | custom\_event\_5\_value\_swipe\_up                  | custom\_event\_5\_value\_engaged\_view                  | custom\_event\_5\_value\_view                  |

### Allowed combinations of attribution windows[​**](#allowed-combinations-of-attribution-windows "Copy to clipboard")

Engaged View Conversions are always available with a fixed attribution window of two days, for this reason there is no need to provide an attribution window.

| View window | Swipe window 1\_DAY | Swipe window 7\_DAY | Swipe window 28\_DAY |
| ----------- | ------------------- | ------------------- | -------------------- |
| none\*      | Allowed             | Allowed             | Allowed              |
| 1\_HOUR     | Allowed             | Allowed             | Allowed              |
| 3\_HOUR     | Allowed             | Allowed             | Allowed              |
| 6\_HOUR     | Allowed             | Allowed             | Allowed              |
| 1\_DAY      | Allowed             | Allowed             | Allowed              |
| 7\_DAY      | Not Allowed         | Allowed             | Allowed              |
| 28\_DAY     | Not Allowed         | Not Allowed         | Allowed              |

\*When using view\_attribution\_window=none no View conversions will be returned

## Attribution windows example[​**](#attribution-windows-example "Copy to clipboard")

```
curl "https://adsapi.snapchat.com/v1/campaigns/04dd5e26-7156-4e07-b2b8-2911ae3aaccc/stats?granularity=DAY&fields=impressions,spend,conversion_add_cart,conversion_add_cart_swipe_up,conversion_add_cart_engaged_view,conversion_add_cart_view,conversion_purchases,conversion_purchases_swipe_up,conversion_purchases_engaged_view,conversion_purchases_view&swipe_up_attribution_window=28_DAY&view_attribution_window=7_DAY&start_time=2025-03-10T00:00:00-08:00&end_time=2025-03-12T00:00:00-08:00"
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "SUCCESS",
  "request_id": "5a1e176f00ff09ef429913ea970001737e616473617069736300016275696c642d65336335336136322d312d3132312d31",
  "timeseries_stats": [
    {
      "sub_request_status": "SUCCESS",
      "timeseries_stat": {
        "id": "04dd5e26-7156-4e07-b2b8-2911ae3aaccc",
        "type": "CAMPAIGN",
        "granularity": "DAY",
        "swipe_up_attribution_window": "28_DAY",
        "view_attribution_window": "7_DAY",
        "start_time": "2025-03-10T00:00:00-08:00",
        "end_time": "2025-03-12T00:00:00-08:00",
        "finalized_data_end_time": "2025-03-20T00:00:00.000-08:00",
        "timeseries": [
          {
            "start_time": "2025-03-10T00:00:00-08:00",
            "end_time": "2025-03-12T00:00:00-08:00",
            "stats": {
              "impressions": 63027,
              "spend": 190136020,
              "conversion_purchases": 23,
              "conversion_purchases_swipe_up": 6,
              "conversion_purchases_engaged_view": 10,
              "conversion_purchases_view": 7,
              "conversion_add_cart": 27,
              "conversion_add_cart_swipe_up": 8,
              "conversion_add_cart_engaged_view": 7,
              "conversion_add_cart_view": 12
            }
          },
          {
            "start_time": "2025-03-10T00:00:00-08:00",
            "end_time": "2025-03-12T00:00:00-08:00",
            "stats": {
              "impressions": 74153,
              "spend": 200905774,
              "conversion_purchases": 12,
              "conversion_purchases_swipe_up": 3,
              "conversion_purchases_engaged_view": 2,
              "conversion_purchases_view": 7,
              "conversion_add_cart": 26,
              "conversion_add_cart_swipe_up": 5,
              "conversion_add_cart_engaged_view": 6,
              "conversion_add_cart_view": 15
            }
          }
        ]
      }
    }
  ]
}
```

Show more▼

This retrieves insights broken down by specified attribution windows.

## Reporting for Dynamic Product Ads (DPA)[​**](#reporting-for-dynamic-product-ads-dpa "Copy to clipboard")

Snapchat now offers a reporting API endpoint so that advertisers can retrieve product-level reporting for Dynamic Product Ads. This report allows advertisers to understand how their campaigns, ad squads, ads delivered & performed for individual products. Reports can only be pulled with a 1 day date range for TOTAL granularity. There are two types of reports that can be retrieved. These are the full reports using the async API and the top-k report using the regular API.

### Supported Breakdowns[​**](#supported-breakdowns "Copy to clipboard")

* Results can be broken down by campaign, ad squad, and ad
* Results can be broken down by date or total

### Supported Metrics[​**](#supported-metrics "Copy to clipboard")

| Field name           | Description                            |
| -------------------- | -------------------------------------- |
| product\_impressions | number of impressions for a product ID |
| swipes               |                                        |
| spend                | microcents local currency              |

### Report Requirements[​**](#report-requirements "Copy to clipboard")

* Reports must be 1 day in length
* Start (start\_time) & End Date (end\_time) must be specified

## Full reports for DPA (Async)[​**](#full-reports-for-dpa-async "Copy to clipboard")

Due to the size of reports, DPA reporting runs on Snapchat’s asynchronous API and returns a file for the full DPA breakdown. The API call to the stats endpoint for a DPA report returns a report run ID. This run ID can be used to make a subsequent call to the stats\_report endpoint to check its status. Upon completion, a signed URL is generated to download the report as a CSV; this CSV has a time to live of 24 hours.

> Stats request - Step 1

```
curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats?breakdown=campaign&granularity=DAY&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY&start_time=2023-03-17&end_time=2023-03-18&fields=product_impressions,swipes,spend&position_stats=false&platform_stats=false&report_dimension=product&omit_empty=true&async=true&async_format=csv" -H "Authorization: Bearer meowmeowmeow"
```

```
{
  "request_status": "SUCCESS",
  "request_id": "<ID>",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6"
      }
    }
  ]
}
```

### Additional Request Parameters[​**](#additional-request-parameters "Copy to clipboard")

These are the specific request parameters necessary to call the DPA Async report API

| Attribute         | Values  |
| ----------------- | ------- |
| report\_dimension | product |
| async             | true    |
| async\_format     | csv     |

### Response - async\_stats\_report Object[​**](#response---async_stats_report-object "Copy to clipboard")

| Attribute       | Description                                                                                                                               | Values                                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| report\_run\_id | the ID of your reporting task                                                                                                             | eg: "ASYNC\_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6"                                                                                                       |
| async\_status   | The current status of the reporting task. Once this changes to COMPLETED, the result field will be populated with the URL for the report. | RUNNING, COMPLETED                                                                                                                                           |
| result          | This contains the URL of the report file                                                                                                  | eg: "<https://data-transfer.snapads.com/async-report/dpa_full/ASYNC_STATS:0efa41e1-5087-48af-8dbc-2cf8aefasdf66e6/4a6csdf1-3234-484b-b2cf-eeb6f1a63c3f.csv>" |

> CSV request - Step 2

```
curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats_report?report_run_id=ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6" -H "Authorization: Bearer  meowmeowmeow"
```

> Report is running

```
{
  "request_status": "SUCCESS",
  "request_id": "<ID>",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6",
        "async_status": "RUNNING",
        "result": ""
      }
    }
  ]
}
```

> Report is completed

```
{
  "request_status": "SUCCESS",
  "request_id": "<ID>",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6",
        "async_status": "COMPLETED",
        "result": "https://data-transfer.snapads.com/async-report/dpa_full/ASYNC_STATS:0efa41e1-5087-48af-8dbc-2cf8aefasdf66e6/4a6csdf1-3234-484b-b2cf-eeb6f1a63c3f.csv"
      }
    }
  ]
}
```

## Top-K report for DPA[​**](#top-k-report-for-dpa "Copy to clipboard")

To support UI reporting and understand the performance of DPA among products with the highest level of spend, Snapchat supports a Top-K report, which will return the top 50 products per entity by impression volume (Campaign, Ad Set, and Ad). This API is similar to the standard reporting API used for non DPA ads.

### Additional Request Parameters[​**](#additional-request-parameters-1 "Copy to clipboard")

These are the specific request parameters necessary to call the DPA Async report API

| Attribute         | Values        |
| ----------------- | ------------- |
| report\_dimension | product\_topk |

```
curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats?breakdown=campaign&granularity=TOTAL&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY&start_time=2020-03-17T00:00:00-07:00&end_time=2020-03-25T00:00:00-07:00&fields=product_impressions,swipes,spend,total_installs,conversion_purchases&position_stats=false&platform_stats=false&report_dimension=product_topk&omit_empty=true" -H "Authorization: Bearer meowmeowmeow"
```

```
{
    "request_status": "SUCCESS",
    "request_id": "5fb4467d00ff07d2b1b1968d810001737e616473617069736300016275696c642d36393939316436622d312d3430332d3100010142",
    "total_stats": [
        {
            "sub_request_status": "SUCCESS",
            "total_stat": {
                "id": "<ID>",
                "type": "AD_ACCOUNT",
                "granularity": "TOTAL",
                "swipe_up_attribution_window": "28_DAY",
                "view_attribution_window": "1_DAY",
                "start_time": "2020-10-27T00:00:00.000-07:00",
                "end_time": "2020-10-29T00:00:00.000-07:00",
                "finalized_data_end_time": "2020-11-17T00:00:00.000-08:00",
                "breakdown_stats": {
                    "campaign": [
                        {
                            "id": "<CAMPAIGN_ID>",
                            "type": "CAMPAIGN",
                            "granularity": "TOTAL",
                            "start_time": "2020-10-27T00:00:00.000-07:00",
                            "end_time": "2020-10-29T00:00:00.000-07:00",
                            "dimension_stats": [
                                {
                                    "product_id": "56e39d8f1b0dd675f10e0131",
                                    "product_impressions": 84051
                                },
                                {
                                    "product_id": "577dfc15dac4a378150ebab0",
                                    "product_impressions": 55271
                                },
                                {
                                    "product_id": "5694f07db06a78118dd2bbae",
                                    "product_impressions": 47643
                                },
                                {
                                    "product_id": "56dff400cec25a1a9e1271cd",
                                    "product_impressions": 26599
                                },
                                {
                                    "product_id": "56eebe757505925c618e9807",
                                    "product_impressions": 23737
                                },
                                {
                                    "product_id": "569cbb6f16805211bb1f7750",
                                    "product_impressions": 21171
                                },
                                {
                                    "product_id": "57a6fad104e0d075a6084059",
                                    "product_impressions": 19274
                                },
                                {
                                    "product_id": "57ab01b93999d9602c743b8e",
                                    "product_impressions": 12256
                                },
                                {
                                    "product_id": "57ad3c3fd227704b8bab09dc",
                                    "product_impressions": 12248
                                },
                                {
                                    "product_id": "57a6c97c5bd8ec7787ea328f",
                                    "product_impressions": 11340
                                },
                                {
                                    "product_id": "569f56793fe3625b0cf56bd9",
                                    "product_impressions": 7433
                                },
                                {
                                    "product_id": "56e14676ae8c93398a13a7d3",
                                    "product_impressions": 6597
                                },
                                {
                                    "product_id": "56f24379f5f899740ec4c0b5",
                                    "product_impressions": 6438
                                },
                                {
                                    "product_id": "575645a524a8f27640d3d40c",
                                    "product_impressions": 6419
                                },
                                {
                                    "product_id": "5700b35e5581e05ce0b4adc3",
                                    "product_impressions": 6056
                                },
                                {
                                    "product_id": "576130685d3faf6218fd8dac",
                                    "product_impressions": 5701
                                },
                                {
                                    "product_id": "579eba20a037085566e39683",
                                    "product_impressions": 1980
                                },
                                {
                                    "product_id": "57adae01b1ce26244dd4012c",
                                    "product_impressions": 1707
                                },
                                {
                                    "product_id": "57a02216e3ada7734f02b275",
                                    "product_impressions": 1185
                                },
                                {
                                    "product_id": "579b220904af45576fae20a3",
                                    "product_impressions": 1083
                                },
                                {
                                    "product_id": "56b1adcdac5bc550738df9fb",
                                    "product_impressions": 857
                                },
                                {
                                    "product_id": "57623c6d823409625004be5e",
                                    "product_impressions": 736
                                },
                                {
                                    "product_id": "57b14c09689ce95b71558fff",
                                    "product_impressions": 671
                                },
                                {
                                    "product_id": "5779ced99bfad279a9783889",
                                    "product_impressions": 573
                                },
                                {
                                    "product_id": "56c29339a3537416ae4b7822",
                                    "product_impressions": 556
                                }
                                ...
                            ]
                        }
                    ]
                },
                "split_results": []
            }
        }
    ]
}
```

Show more▼

## Viewability Metrics[​**](#viewability-metrics "Copy to clipboard")

Viewability Metrics are available given the following criteria;

* Metrics are available from the 1 April 2021
* Available in all granularities (HOUR, DAY, TOTAL, LIFETIME)
* Metrics cannot be broken down by Insights
* Story Ads are not covered by these metrics

### Metrics[​**](#metrics-1 "Copy to clipboard")

| Metric                   | API field                  | Description                                                                                                                                                                                                           |
| ------------------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Viewable Impressions     | viewable\_impressions      | Number of impressions that were 100% viewable on a user's screen for 1 second for display ads or 2 seconds for video ads.                                                                                             |
| Non-Viewable Impressions | non\_viewable\_impressions | Number of impressions that did not meet the criteria for a viewable impression                                                                                                                                        |
| Viewable Rate            | viewable\_rate             | The percentage of the time that your paid Snap Ad impression met the qualifying viewable impression criteria                                                                                                          |
| Measured Impressions     | measured\_impressions      | Number of impressions that were measured for viewability                                                                                                                                                              |
| Gross Impressions        | gross\_impressions         | Total impressions delivered, this includes invalid traffic which is excluded from spend & all other delivery metrics.                                                                                                 |
| Paid Impressions         | paid\_impressions          | The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter’s viewing session. These impressions are net of invalid traffic. |

## Audience filters[​**](#audience-filters "Copy to clipboard")

Audience filters were deprecated on 1 February 2023, this reporting information is preserved for Audience Filters created prior to the deprecation.

| Field               | Description                                                                                                                                                            | Availability    |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| paid\_impressions   | The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter's viewing session | Real Time       |
| earned\_impressions | The number of times your ad was viewed after being shared by a Snapchatter via Chat or Stories                                                                         | Within 24 hours |
| shares              | The number of times your ad was shared via Chat or Stories                                                                                                             | Real Time       |
| saves               | The number of times your ad was saved to Memories                                                                                                                      | Real Time       |
| spend               | The total spend delivered in microcurrency                                                                                                                             | Real Time       |
| uniques             | The number of unique paid impressions                                                                                                                                  | Within 24 hours |

Stats are available at the Ad, Ad Squad and Campaign levels and are supported for all granularities: HOUR, DAY, TOTAL and LIFETIME.

```
curl "https://adsapi.snapchat.com/v1/adsquads/419d41d7-e4d4-4c13-803c-55e140a0ec1c/stats?granularity=LIFETIME&fields=paid_impressions,shares,saves,spend,uniques,earned_impressions"
  -H "Authorization: Bearer meowmeowmeow"
```

> The above command returns JSON structured like this:

```
{
  "request_status": "SUCCESS",
  "request_id": "59b9cde600ff04b518a3c18db20001737e616473617069736300016275696c642d31386433356533662d312d3130302d3100010148",
  "lifetime_stats": [
    {
      "sub_request_status": "SUCCESS",
      "lifetime_stat": {
        "id": "419d41d7-e4d4-4c13-803c-55e140a0eb1c",
        "type": "AD_SQUAD",
        "granularity": "LIFETIME",
        "stats": {
          "uniques": 186219,
          "spend": 247184000,
          "earned_impressions": 196140,
          "paid_impressions": 199290,
          "shares": 5762,
          "saves": 799
        },
        "start_time": "2016-09-26T00:00:00.000-07:00",
        "end_time": "2017-09-13T00:00:00.000-07:00",
        "finalized_data_end_time": "2017-09-13T00:00:00.000-07:00"
      }
    }
  ]
}
```

### HTTP Request[​**](#http-request-9 "Copy to clipboard")

`GET https://adsapi.snapchat.com/v1/adsquads/{adsquad-id}/stats`

### Parameters[​**](#parameters-8 "Copy to clipboard")

| Parameter  | Description                 |
| ---------- | --------------------------- |
| adsquad-id | Audience filter Ad squad ID |

## Create Lead Gen Report[​**](#create-lead-gen-report "Copy to clipboard")

This request initiates a lead gen report for an Ad Account given the selected start time and end time, the request returns a Report id in the form of `report_run_id` which is then used to retrieve the report itself.

Data collected via Lead Gen Ads is not stored for more than 30 days, this also means that the start time can't be more than 30 days in the past.

```
curl -X POST  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/leads_report?async_format=csv&start_time=2021-12-01T00:00:00-07:00&end_time=2021-12-14T00:00:00-07:00
```

> The above command returns a report\_run\_id:

```
{
  "request_status": "SUCCESS",
  "request_id": "61b8c10a00ff08449824e366290001737e616473617069736300016275696c642d38333537336364642d312d3530332d3000010159",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:2e480f4f-0c2a-463c-a883-841f88175449",
        "async_status": "STARTED"
      }
    }
  ]
}
```

### HTTP Request[​**](#http-request-10 "Copy to clipboard")

`POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/leads_report`

### Parameters[​**](#parameters-9 "Copy to clipboard")

| Parameter     | Default value | Description              |
| ------------- | ------------- | ------------------------ |
| async\_format | csv           |                          |
| start\_time   |               | Start time in ISO format |
| end\_time     |               | End time in ISO format   |

## Fetch Lead Gen Report[​**](#fetch-lead-gen-report "Copy to clipboard")

This request uses the `report_run_id` in order to fetch the status of a report.

If the report is ready the request returns the URL of a list of leads in CSV format, the `async_status` indicates whether the report is completed and ready to be downloaded. If the report is ready the value of the `async_status` is COMPLETED, if the report is still running the `async_status` will be RUNNING.

When a report is completed the url for downloading the data is found in the result attribute. This URL is valid for 48 hours.

```
curl "https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/leads_report?report_run_id=ASYNC_STATS:7766eab2-643e-4117-8b58-c9ee3fe854f3" \
  -H "Authorization: Bearer meowmeowmeow"
```

> Example #1 - Report in progress

```
{
  "request_status": "SUCCESS",
  "request_id": "61b8bf2d00ff07c8f092caf50b0001737e616473617069736300016275696c642d38333537336364642d312d3530332d3000010142",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:7766eae2-643e-4117-8b58-c9ee3fe854f3",
        "async_status": "RUNNING"
      }
    }
  ]
}
```

```
curl "https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/leads_report?report_run_id=ASYNC_STATS:7766eeb2-643e-4117-8b58-c9ee3fe854f3" \
  -H "Authorization: Bearer meowmeowmeow"
```

> Example #2 - Completed report

```
{
  "request_status": "SUCCESS",
  "request_id": "61b8bf2d00ff07c8f092caf50b0001737e616473617069736300016275696c642d38333537336364642d312d3530332d3000010142",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:7766eeb2-643e-4117-8b58-c9ee3fe854f3",
        "async_status": "COMPLETED",
        "result": "https://data-transfer.snapads.com/async-report/native_lead/ASYNC_STATS:7766eeb2-643e-4117-8b58-c9ee3fe854f3/00ea875b-1645-4fe8-8825-aa7a351b260b.csv"
      }
    }
  ]
}
```

### HTTP Request[​**](#http-request-11 "Copy to clipboard")

`GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/leads_report`

### Parameters[​**](#parameters-10 "Copy to clipboard")

| Parameter       | Default value | Description                                                |
| --------------- | ------------- | ---------------------------------------------------------- |
| report\_run\_id | Report id     | The Report id returned by API request to initiate a report |

### Lead Gen Report[​**](#lead-gen-report "Copy to clipboard")

This is a list of fields in the Lead Gen Report and their properties.

| Field Name       | Type     | Max Length                                    | Required?                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Example                                                                                                                                                                               |
| ---------------- | -------- | --------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Date             | Datetime | 17                                            | Yes                                        | Date that lead was submitted. The timestamp is truncated to the beginning of the local day and the time is always "00:00:00"<br />Format: "yyyy-MM-dd 00:00:00"                                                                                                                                                                                                                                                                                                                                                                                                                         | 2022-05-11 00:00:00                                                                                                                                                                   |
| Ad Account Id    | String   | 36                                            | Yes                                        | Ad account ID associated with the ad that generated the lead. Hyphen separated UUID string.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | f0d4666f-9f60-4df7-94c8-423ca55b2a17                                                                                                                                                  |
| Campaign Id      | String   | 36                                            | Yes                                        | Campaign ID associated with ad that generated the lead. Hyphen separated UUID string.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | 033fe5aa-59b4-423d-8ab5-b7a7cf6c5242                                                                                                                                                  |
| Ad Set Id        | String   | 36                                            | Yes                                        | Ad Set ID associated with ad that generated the lead. Hyphen separated UUID string.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | ebad6081-f387-4bce-b6dc-9ea4d2cbefbc                                                                                                                                                  |
| Ad Id            | String   | 36                                            | Yes                                        | Ad ID associated with ad that generated the lead. Hyphen separated UUID string.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | ca72035c-9f8d-409b-abee-5e2e0c943f9c                                                                                                                                                  |
| First Name       | String   |                                               | Yes                                        | First name of Snapchat User                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Jane                                                                                                                                                                                  |
| Last Name        | String   |                                               | Yes                                        | Last name of Snapchat User                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Smith                                                                                                                                                                                 |
| Phone Number     | String   |                                               | Yes (Either Email Address or Phone Number) | ex: 818-555-1234, +13105558765<br />\*Not all formatted the same                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | 818-555-1234<br />+13105558765                                                                                                                                                        |
| Email Address    | String   |                                               | Yes (Either Email Address or Phone Number) | Email address of Snapchat user                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | <johndoe@gmail.com>                                                                                                                                                                   |
| Address Line 1   | String   |                                               | No                                         | Address of Snapchat user, Line 1                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | 19330 25th Ave                                                                                                                                                                        |
| Address Line 2   | String   |                                               | No                                         | Address of Snapchat user, Line 2                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Unit 3                                                                                                                                                                                |
| Address Level 1  | String   |                                               | No                                         | Address city or town                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Seattle                                                                                                                                                                               |
| Address Level 2  | String   |                                               | No                                         | Address state, province, or region                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | WA                                                                                                                                                                                    |
| Postal Code      | String   |                                               | No                                         | Postal code of Snapchat user                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | 94012                                                                                                                                                                                 |
| Birthday         | Date     | 10                                            | No                                         | Snapchat user's birthdate. Formatted "MM/DD/YYYY"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | 05/20/1998                                                                                                                                                                            |
| Job Title        | String   |                                               | No                                         | Job title                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Marketing Manager                                                                                                                                                                     |
| Company Name     | String   |                                               | No                                         | Company name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Snap, Inc.                                                                                                                                                                            |
| Custom Field 1   | String   |                                               | No                                         | Can be one of the following based on the type of Custom Question:<br />**Single-select:** key-value object that contains the answer that the user selected and "true": {answer<!-- -->:true<!-- -->}<br />**Multi-select:** key-value object that contains all of the answers that the user selected and "true": {answer1<!-- -->:true<!-- -->, answer2: true, answer3: true, answer4<!-- -->:true<!-- -->}<br />**Short Answer**: String that contains the answer that the user entered into the form.<br />**Date Widget:** The date that the user entered in the format "MM/DD/YYYY" | {Pizza<!-- -->:true<!-- -->}<br />{Pizza<!-- -->:true<!-- -->, Sushi<!-- -->:true<!-- -->, Hamburgers<!-- -->:true<!-- -->}<br />This is what I entered into the form<br />01/02/2022 |
| Custom Field 2   | String   |                                               | No                                         | "                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                                                                                                                                                                                       |
| Custom Field 3   | String   |                                               | No                                         | "                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                                                                                                                                                                                       |
| Custom Field 4   | String   |                                               | No                                         | "                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                                                                                                                                                                                       |
| Custom Field 5   | String   |                                               | No                                         | "                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                                                                                                                                                                                       |
| Custom Field 6   | String   |                                               | No                                         | "                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                                                                                                                                                                                       |
| Custom Field 7   | String   |                                               | No                                         | "                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                                                                                                                                                                                       |
| Custom Field 8   | String   |                                               | No                                         | "                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |                                                                                                                                                                                       |
| Consent 1        | String   | Disclaimers: 80<br />Answer: 5<br />Total: 86 | No                                         | Disclaimer in the consent section of the form and the user's response. Data is a key-value string in the following format:<br />disclaimer<!-- -->:answer<br />"answer" will be "true" if the user consented and "false" if they did not consent.                                                                                                                                                                                                                                                                                                                                       | do you consent?<!-- -->:true<br /><https://www.example.com>:false                                                                                                                     |
| Consent 2        | String   | Disclaimers: 80<br />Answer: 5<br />Total: 86 | No                                         | Disclaimer in the consent section of the form and the user's response. Data is a key-value string in the following format:<br />disclaimer<!-- -->:answer<br />"answer" will be "true" if the user consented and "false" if they did not consent.                                                                                                                                                                                                                                                                                                                                       | do you consent?<!-- -->:true<br /><https://www.example.com>:false                                                                                                                     |
| Preferred Status | String   | Preferred \| Non-Preferred                    | No                                         | Indicates whether this lead is preferred or non-preferred based on the responses to the qualifying questions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Preferred                                                                                                                                                                             |

### Example Lead Gen Report[​**](#example-lead-gen-report "Copy to clipboard")

Here is an example Lead Gen Report .csv file. All the sample data is made-up; no actual user data is included.
