--- openapi: 3.0.3 info: title: Braze REST API – Export Canvas data summary analytics description: | ## Prerequisites To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key-permissions) 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/). 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: | ## 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. operationId: get_canvas_data_summary_get_canvas_analytics_summary parameters: - name: canvas_id in: query required: true description: See [Canvas API identifier]({{site.baseurl}}/api/identifier_types/). schema: type: string example: canvas_identifier - name: ending_at in: query required: true description: | End date for the data export. Defaults to the time of the request. **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. schema: type: string format: date-time example: "2018-05-30T23:59:59-05:00" - name: starting_at in: query required: false description: | Start date for the data export. Either `length` or `starting_at` is required. **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. schema: type: string format: date-time example: "2018-05-28T23:59:59-05:00" - 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 minimum: 1 maximum: 14 example: 5 - name: include_variant_breakdown in: query required: false description: Whether to include variant statistics (defaults to `false`). schema: type: boolean default: false example: true - name: include_step_breakdown in: query required: false description: Whether to include step statistics (defaults to `false`). schema: type: boolean default: false example: true - name: include_deleted_step_data in: query required: false description: Whether to include step statistics for deleted steps (defaults to `false`). schema: type: boolean default: false example: true responses: "200": description: The request succeeded and the response body includes the Canvas rollup analytics. No action needed. content: application/json: schema: $ref: '#/components/schemas/CanvasAnalyticsSummaryResponse' examples: success: summary: Canvas data summary with variant and step breakdowns value: data: name: Example Canvas total_stats: revenue: 25.0 conversions: 5 conversions_by_entry_time: 5 entries: 100 variant_stats: 00000000-0000-0000-0000-0000000000000: name: Variant 1 revenue: 25.0 conversions: 5 entries: 100 step_stats: 00000000-0000-0000-0000-0000000000000: name: Welcome step revenue: 25.0 conversions: 5 conversions_by_entry_time: 5 messages: android_push: - sent: 100 opens: 20 influenced_opens: 30 bounces: 1 message: success multiple_conversion_events: summary: Canvas with multiple conversion events description: The following sample response shows an example of the response returned when the Canvas has multiple conversion events configured. value: data: name: Example Canvas total_stats: revenue: 25.0 entries: 100 conversions: 5 conversions_by_entry_time: 5 conversions1: 3 conversions1_by_entry_time: 3 conversions2: 2 conversions2_by_entry_time: 2 conversions3: 1 conversions3_by_entry_time: 1 variant_stats: 00000000-0000-0000-0000-0000000000000: name: Variant 1 revenue: 25.0 conversions: 5 conversions_by_entry_time: 5 conversions1: 3 conversions1_by_entry_time: 3 conversions2: 2 conversions2_by_entry_time: 2 conversions3: 1 conversions3_by_entry_time: 1 entries: 100 step_stats: 00000000-0000-0000-0000-0000000000000: name: Welcome step revenue: 25.0 conversions: 5 conversions_by_entry_time: 5 conversions1: 3 conversions1_by_entry_time: 3 conversions2: 2 conversions2_by_entry_time: 2 conversions3: 1 conversions3_by_entry_time: 1 messages: android_push: - sent: 100 opens: 20 influenced_opens: 30 bounces: 1 message: success "400": description: | Bad request. To resolve it: - **The `canvas_id` is missing or isn't a string:** Pass a valid `canvas_id` string. Find it with the [Export Canvas list endpoint]({{site.baseurl}}/api/endpoints/export/canvas/get_canvases/). - **The `ending_at` value isn't a valid datetime:** Pass `ending_at` as an ISO 8601 datetime. - **The `ending_at` value is out of range:** Pass an `ending_at` within the allowed range. - **The `length` isn't an integer:** Pass `length` as an integer between 1 and 14. - **The `length` is outside the allowed range:** Pass `length` between 1 and 14. - **Neither a valid `starting_at` nor a `length` was provided:** Include `length`, or a valid `starting_at`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_canvas_id: summary: Missing or invalid canvas_id value: message: canvas_id must be a string of the Canvas api identifier ending_at_improperly_formatted: summary: ending_at isn't a valid datetime value: message: ending_at time is improperly formatted ending_at_out_of_range: summary: ending_at out of range value: message: ending_at time is out of range length_not_integer: summary: length isn't an integer value: message: an integer length must be provided length_out_of_range: summary: length outside the allowed range value: message: series range must be greater than 0 and less than 14 missing_start: summary: Neither starting_at nor length value: message: either a properly formatted starting time OR length must be provided "401": description: | Unauthorized. The REST API key is missing, malformed, or sent to the wrong REST endpoint. 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). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_api_key: summary: Invalid API key value: message: 'Invalid API key: YOUR_REST_API_KEY' "403": description: Access denied. The REST API key doesn't have the required permission. Use a REST API key that has the `canvas.data_summary` permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: access_denied: summary: Missing permission value: message: Access Denied "429": description: | Rate limited. You exceeded the rate limit for this endpoint. Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: over_rate_limit: summary: Over rate limit value: message: You have exceeded your limit of 250000 requests per hour. Please contact your account executive to increase your limit. If you do not have their info, you may contact Braze directly at https://www.braze.com/contact/. 5XX: description: | Internal server error. An unexpected error occurred on the Braze server. Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: REST API key description: | REST API keys are created in the Braze dashboard at **Settings → APIs and Identifiers → API Keys**. The key must include the `canvas.data_summary` permission. Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`. schemas: AdditionalConversionStats: title: Additional conversion event stats type: object description: Conversion fields for the second, third, and fourth conversion events. Fifth and later events follow the same pattern. properties: conversions1: type: integer description: The number of conversions for the second conversion event. conversions1_by_entry_time: type: integer description: The number of conversions for the second conversion event by entry time. conversions2: type: integer description: The number of conversions for the third conversion event. conversions2_by_entry_time: type: integer description: The number of conversions for the third conversion event by entry time. conversions3: type: integer description: The number of conversions for the fourth conversion event. conversions3_by_entry_time: type: integer description: The number of conversions for the fourth conversion event by entry time. CanvasSummaryTotalStats: title: Canvas total stats allOf: - type: object properties: revenue: type: number description: The number of dollars of revenue (USD). entries: type: integer description: The number of entries. conversions: type: integer description: The number of conversions for the primary conversion event. conversions_by_entry_time: type: integer description: The number of conversions for the conversion event by entry time. With multiple conversion events, this is the number of conversions for the primary conversion event by entry time. - $ref: '#/components/schemas/AdditionalConversionStats' CanvasSummaryVariantStats: title: Canvas variant stats allOf: - 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 for the primary conversion event. conversions_by_entry_time: type: integer description: The number of conversions for the primary conversion event by entry time. entries: type: integer description: The number of entries. - $ref: '#/components/schemas/AdditionalConversionStats' CanvasSummaryStepStats: title: Canvas step stats allOf: - 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 for the primary conversion event. conversions_by_entry_time: type: integer description: The number of conversions for the conversion event by entry time. With multiple conversion events, this is the number of conversions for the primary conversion event by entry time. messages: type: object description: Message stats for the step, keyed by name of channel. The response can include more channels than shown. properties: android_push: type: array items: type: object description: The response can include more stats for the channel than shown. 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). **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. bounces: type: integer description: The number of bounces. - $ref: '#/components/schemas/AdditionalConversionStats' CanvasAnalyticsSummaryResponse: title: Export Canvas data summary analytics response type: object properties: data: type: object properties: name: type: string description: The Canvas name. total_stats: $ref: '#/components/schemas/CanvasSummaryTotalStats' variant_stats: type: object description: Optional. Stats for each variant, keyed by the API identifier for the variant. See `include_variant_breakdown`. additionalProperties: $ref: '#/components/schemas/CanvasSummaryVariantStats' step_stats: type: object description: Optional. Stats for each step, keyed by the API identifier for the step. See `include_step_breakdown`. additionalProperties: $ref: '#/components/schemas/CanvasSummaryStepStats' message: type: string description: Returns 'success' when the request completes without errors. example: success ErrorResponse: title: Error 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.