--- openapi: 3.0.3 info: title: Braze REST API – Export Canvas data summary analytics description: 'Use this endpoint to export rollups of time series data for a Canvas, providing a concise summary of Canvas results. ' version: 1.0.0 contact: name: Braze Support url: https://www.braze.com/docs/braze_support/ license: name: Braze Documentation url: https://www.braze.com/docs/api/home/ servers: - url: https://rest.iad-01.braze.com description: US-01 - url: https://rest.iad-02.braze.com description: US-02 - url: https://rest.iad-03.braze.com description: US-03 - url: https://rest.iad-04.braze.com description: US-04 - url: https://rest.iad-05.braze.com description: US-05 - url: https://rest.iad-06.braze.com description: US-06 - url: https://rest.iad-07.braze.com description: US-07 - url: https://rest.iad-08.braze.com description: US-08 - url: https://rest.us-10.braze.com description: US-10 - url: https://rest.fra-01.braze.eu description: EU-01 - url: https://rest.fra-02.braze.eu description: EU-02 - url: https://rest.au-01.braze.com description: AU-01 - url: https://rest.id-01.braze.com description: ID-01 - url: https://rest.jp-01.braze.com description: JP-01 - url: https://rest.kr-01.braze.com description: KR-01 security: - BearerAuth: [] paths: "/canvas/data_summary": get: summary: Export Canvas data summary analytics description: | ## Prerequisites To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key/) with the `canvas.data_summary` permission. ## Rate limit We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/). ## Request parameters The following table lists the request parameters for this endpoint. | Parameter | Required | Data Type | Description | | --------- | -------- | --------- | ----------- | | `canvas_id` | Required | String | See [Canvas API identifier]({{site.baseurl}}/api/identifier_types/). | | `ending_at` | Required | Datetime
([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | End date for the data export. Defaults to the time of the request. | | `starting_at` | Optional* | Datetime
([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | Start date for the data export.

* Either `length` or `starting_at` is required. | | `length` | Optional* | Integer | Maximum number of days before `ending_at` included in the returned series. Must be between 1 and 14 (inclusive).

* Either `length` or `starting_at` is required. | | `include_variant_breakdown` | Optional | Boolean | Whether to include variant statistics (defaults to `false`). | | `include_step_breakdown` | Optional | Boolean | Whether to include step statistics (defaults to `false`). | | `include_deleted_step_data` | Optional | Boolean | Whether to include step statistics for deleted steps (defaults to `false`). | **Important:** **Time zone alignment:** Canvas analytics are aggregated by day in your company's configured time zone in Braze (the same time zone the dashboard uses). The API normalizes `starting_at` and `ending_at` to midnight in that time zone. Make sure your timestamps align with your company's time zone so that your stats match the dashboard. For example, if your company time is UTC+2, then the timestamp should be 12 am UTC+2. ## Example request The following sample request shows an example of how to export Canvas data summary analytics. ``` curl --location -g --request GET 'https://rest.iad-01.braze.com/canvas/data_summary?canvas_id={{canvas_id}}&ending_at=2018-05-30T23:59:59-05:00&starting_at=2018-05-28T23:59:59-05:00&length=5&include_variant_breakdown=true&include_step_breakdown=true&include_deleted_step_data=true' \ --header 'Authorization: Bearer YOUR_REST_API_KEY' ``` ## Response The following sample response shows an example of the response returned when you export Canvas data summary analytics. ```json { "data": { "name": (string) the Canvas name, "total_stats": { "revenue": (float) the number of dollars of revenue (USD), "conversions": (int) the number of conversions, "conversions_by_entry_time": (int) the number of conversions for the conversion event by entry time, "entries": (int) the number of entries }, "variant_stats": (optional) { "00000000-0000-0000-0000-0000000000000": (string) the API identifier for the variant { "name": (string) the name of the variant, "revenue": (float) the number of dollars of revenue (USD), "conversions": (int) the number of conversions, "entries": (int) the number of entries }, ... (more variants) }, "step_stats": (optional) { "00000000-0000-0000-0000-0000000000000": (string) the API identifier for the step { "name": (string) the name of the step, "revenue": (float) the number of dollars of revenue (USD), "conversions": (int) the number of conversions, "conversions_by_entry_time": (int) the number of conversions for the conversion event by entry time, "messages": { "android_push": (name of channel) [ { "sent": (int) the number of sends, "opens": (int) the number of opens, "influenced_opens": (int) the total number of opens (includes both direct opens and influenced opens), "bounces": (int) the number of bounces ... (more stats for channel) } ], ... (more channels) } }, ... (more steps) } }, "message": (string) returns 'success' when the request completes without errors } ``` **Important:** **`influenced_opens` field:** In the API response, the `influenced_opens` field represents the total number of opens (both direct and influenced opens combined). In the Braze dashboard, 'influenced opens' refers only to influenced opens, excluding direct opens. This is due to a legacy naming convention in the API. ### Conversion event fields The response includes one pair of conversion fields for each conversion event configured on the Canvas. The primary conversion event uses `conversions` and `conversions_by_entry_time`. Each additional event uses the same base name with a numeric suffix that starts at `1` for the second event and increases by one for each additional event. The following table lists how conversion event order maps to response field names. | Conversion event order on the Canvas | Conversions field | By entry time field | | --- | --- | --- | | Primary | `conversions` | `conversions_by_entry_time` | | Second | `conversions1` | `conversions1_by_entry_time` | | Third | `conversions2` | `conversions2_by_entry_time` | | Fourth | `conversions3` | `conversions3_by_entry_time` | Fifth and later events follow the same pattern (for example, `conversions4` and `conversions4_by_entry_time`). These fields appear in `total_stats` and, when you request breakdowns, in `variant_stats` and `step_stats` using the same names. **Note:** In `total_stats`, `variant_stats`, and `step_stats`, `conversions` is the count for the [primary conversion event]({{site.baseurl}}/user_guide/messaging/messaging_fundamentals/conversion_events/) of the Canvas. When you configure additional conversion events, the payload can also include `conversions1`, `conversions2`, and higher-indexed fields for the second, third, and further events. This is similar to the [multivariate response]({{site.baseurl}}/api/endpoints/export/campaigns/get_campaign_analytics/#multivariate-response) for the `/campaigns/data_series` endpoint. Where present, fields ending in `_by_entry_time` attribute those conversions by Canvas entry time. The following sample response shows an example of the response returned when the Canvas has multiple conversion events configured. ```json { "data": { "name": (string) the Canvas name, "total_stats": { "revenue": (float) the number of dollars of revenue (USD), "entries": (int) the number of entries, "conversions": (int) the number of conversions for the primary conversion event, "conversions_by_entry_time": (int) the number of conversions for the primary conversion event by entry time, "conversions1": (optional, int) the number of conversions for the second conversion event, "conversions1_by_entry_time": (optional, int) the number of conversions for the second conversion event by entry time, "conversions2": (optional, int) the number of conversions for the third conversion event, "conversions2_by_entry_time": (optional, int) the number of conversions for the third conversion event by entry time, "conversions3": (optional, int) the number of conversions for the fourth conversion event, "conversions3_by_entry_time": (optional, int) the number of conversions for the fourth conversion event by entry time }, "variant_stats": (optional) { "00000000-0000-0000-0000-0000000000000": (string) the API identifier for the variant { "name": (string) the name of the variant, "revenue": (float) the number of dollars of revenue (USD), "conversions": (int) the number of conversions for the primary conversion event, "conversions_by_entry_time": (optional, int) the number of conversions for the primary conversion event by entry time, "conversions1": (optional, int) the number of conversions for the second conversion event, "conversions1_by_entry_time": (optional, int) the number of conversions for the second conversion event by entry time, "conversions2": (optional, int) the number of conversions for the third conversion event, "conversions2_by_entry_time": (optional, int) the number of conversions for the third conversion event by entry time, "conversions3": (optional, int) the number of conversions for the fourth conversion event, "conversions3_by_entry_time": (optional, int) the number of conversions for the fourth conversion event by entry time, "entries": (int) the number of entries }, ... (more variants) }, "step_stats": (optional) { "00000000-0000-0000-0000-0000000000000": (string) the API identifier for the step { "name": (string) the name of the step, "revenue": (float) the number of dollars of revenue (USD), "conversions": (int) the number of conversions for the primary conversion event, "conversions_by_entry_time": (int) the number of conversions for the primary conversion event by entry time, "conversions1": (optional, int) the number of conversions for the second conversion event, "conversions1_by_entry_time": (optional, int) the number of conversions for the second conversion event by entry time, "conversions2": (optional, int) the number of conversions for the third conversion event, "conversions2_by_entry_time": (optional, int) the number of conversions for the third conversion event by entry time, "conversions3": (optional, int) the number of conversions for the fourth conversion event, "conversions3_by_entry_time": (optional, int) the number of conversions for the fourth conversion event by entry time, "messages": { "android_push": (name of channel) [ { "sent": (int) the number of sends, "opens": (int) the number of opens, "influenced_opens": (int) the total number of opens (includes both direct opens and influenced opens), "bounces": (int) the number of bounces ... (more stats for channel) } ], ... (more channels) } }, ... (more steps) } }, "message": (string) returns 'success' when the request completes without errors } ``` ## Response status codes The following table lists the responses for this endpoint, the error message you may receive, and how to resolve it. | Status code | Meaning | Error message | How to resolve | | --- | --- | --- | --- | | `200 OK` | The request succeeded and the response body includes the Canvas rollup analytics. | `success` | No action needed. | | `400 Bad Request` | The `canvas_id` is missing or isn't a string. | `canvas_id must be a string of the Canvas api identifier` | Pass a valid `canvas_id` string. Find it with the [Export Canvas list endpoint]({{site.baseurl}}/api/endpoints/export/canvas/get_canvases/). | | `400 Bad Request` | The `ending_at` value isn't a valid datetime. | `ending_at time is improperly formatted` | Pass `ending_at` as an ISO 8601 datetime. | | `400 Bad Request` | The `ending_at` value is out of range. | `ending_at time is out of range` | Pass an `ending_at` within the allowed range. | | `400 Bad Request` | The `length` isn't an integer. | `an integer length must be provided` | Pass `length` as an integer between 1 and 14. | | `400 Bad Request` | The `length` is outside the allowed range. | `series range must be greater than 0 and less than 14` | Pass `length` between 1 and 14. | | `400 Bad Request` | Neither a valid `starting_at` nor a `length` was provided. | `either a properly formatted starting time OR length must be provided` | Include `length`, or a valid `starting_at`. | | `401 Unauthorized` | The REST API key is missing, malformed, or sent to the wrong REST endpoint. | `Invalid API key` | Send the key as `Authorization: Bearer YOUR_REST_API_KEY` to the correct [REST endpoint]({{site.baseurl}}/api/basics/#endpoints). For more causes, see [Errors and responses]({{site.baseurl}}/api/errors/#fatal-errors). | | `403 Access Denied` | The REST API key doesn't have the required permission. | `Access Denied` | Use a REST API key that has the `canvas.data_summary` permission. | | `429 Rate Limited` | You exceeded the rate limit for this endpoint. | `Over rate limit` | Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/). | | `5XX Internal Server Error` | An unexpected error occurred on the Braze server. | `Internal Server Error` | Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). | **Tip:** For help with CSV and API exports, visit [Export troubleshooting]({{site.baseurl}}/user_guide/data/distribution/export_braze_data/export_troubleshooting/). operationId: get_canvas_data_summary_get_canvas_analytics_summary tags: - Export responses: '200': description: The request succeeded and the response body includes the Canvas rollup analytics. content: application/json: schema: $ref: '#/components/schemas/CanvasAnalyticsSummaryResponse' '400': description: |- Bad Request. Causes include: - `canvas_id must be a string of the Canvas api identifier` — The `canvas_id` is missing or isn't a string. - `ending_at time is improperly formatted` — The `ending_at` value isn't a valid datetime. - `ending_at time is out of range` — The `ending_at` value is out of range. - `an integer length must be provided` — The `length` isn't an integer. - `series range must be greater than 0 and less than 14` — The `length` is outside the allowed range. - `either a properly formatted starting time OR length must be provided` — Neither a valid `starting_at` nor a `length` was provided. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: The REST API key is missing, malformed, or sent to the wrong REST endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: The REST API key doesn't have the required permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: You exceeded the rate limit for this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '5XX': description: An unexpected error occurred on the Braze server. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' parameters: - name: canvas_id in: query required: true description: See Canvas API identifier. schema: type: string - name: ending_at in: query required: true description: End date for the data export. Defaults to the time of the request. schema: type: string - name: starting_at in: query required: false description: Start date for the data export. * Either `length` or `starting_at` is required. schema: type: string - name: length in: query required: false description: Maximum number of days before `ending_at` included in the returned series. Must be between 1 and 14 (inclusive). * Either `length` or `starting_at` is required. schema: type: integer - name: include_variant_breakdown in: query required: false description: Whether to include variant statistics (defaults to `false`). schema: type: boolean - name: include_step_breakdown in: query required: false description: Whether to include step statistics (defaults to `false`). schema: type: boolean - name: include_deleted_step_data in: query required: false description: Whether to include step statistics for deleted steps (defaults to `false`). schema: type: boolean components: schemas: CanvasAnalyticsSummaryResponse: type: object properties: data: type: object properties: name: type: string description: The Canvas name. total_stats: type: object properties: revenue: type: number description: The number of dollars of revenue (USD). conversions: type: integer description: The number of conversions. conversions_by_entry_time: type: integer description: The number of conversions for the conversion event by entry time. entries: type: integer description: The number of entries. variant_stats: type: object properties: 00000000-0000-0000-0000-0000000000000: type: object properties: name: type: string description: The name of the variant. revenue: type: number description: The number of dollars of revenue (USD). conversions: type: integer description: The number of conversions. entries: type: integer description: The number of entries. step_stats: type: object properties: 00000000-0000-0000-0000-0000000000000: type: object properties: name: type: string description: The name of the step. revenue: type: number description: The number of dollars of revenue (USD). conversions: type: integer description: The number of conversions. conversions_by_entry_time: type: integer description: The number of conversions for the conversion event by entry time. messages: type: object properties: android_push: type: array items: type: object properties: sent: type: integer description: The number of sends. opens: type: integer description: The number of opens. influenced_opens: type: integer description: The total number of opens (includes both direct opens and influenced opens). bounces: type: integer description: The number of bounces. message: type: string description: Returns 'success' when the request completes without errors. ErrorResponse: type: object properties: message: type: string description: The error message describing why the request failed. errors: type: array description: Non-fatal errors encountered while processing the request. Data unaffected by these errors is still processed. items: type: object properties: type: type: string description: The error type. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: REST API key