---
openapi: 3.0.3
info:
title: Braze REST API – Export Canvas data series analytics
description: 'Use this endpoint to export time series data for a Canvas.
'
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_series":
get:
summary: Export Canvas data series analytics
description: |
## Prerequisites
To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key/) with the `canvas.data_series` 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) | Date on which the data export should end. Defaults to time of the request. |
| `starting_at` | Optional* | Datetime
([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | Date on which the data export should begin.
* Either `length` or `starting_at` is required. |
| `length` | Optional* | Integer | Maximum number of days before `ending_at` to include in the returned series. Must be between 1 and 14 (inclusive).
* Either `length` or `starting_at` is required. |
| `include_variant_breakdown` | Optional | Boolean | Whether or not to include variant statistics (defaults to `false`). |
| `include_step_breakdown` | Optional | Boolean | Whether or not to include step statistics (defaults to `false`). |
| `include_deleted_step_data` | Optional | Boolean | Whether or not to include step statistics for deleted steps (defaults to `false`). |
## Example request
The following sample request shows an example of how to export Canvas data series analytics.
```
curl --location -g --request GET 'https://rest.iad-01.braze.com/canvas/data_series?canvas_id={{canvas_id}}&ending_at=2018-05-30T23:59:59-5:00&starting_at=2018-05-28T23:59:59-5:00&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 series analytics.
```json
{
"data": {
"name": (string) the Canvas name,
"stats": [
{
"time": (string) the date as ISO 8601 date,
"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 variant,
"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
},
... (more variants)
},
"step_stats": (optional) {
"00000000-0000-0000-0000-0000000000000": (string) the API identifier for the step {
"name": (string) the name of 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": {
"email": [
{
"sent": (int) the number of sends,
"opens": (int) the number of opens,
"unique_opens": (int) the number of unique opens,
"clicks": (int) the number of clicks
... (more stats)
}
],
"sms" : [
{
"sent": (int) the number of sends,
"sent_to_carrier" : (int) the number of messages sent to the carrier,
"delivered": (int)the number of delivered messages,
"rejected": (int) the number of rejected messages,
"delivery_failed": (int) the number of failed deliveries,
"clicks": (int) the number of clicks on shortened links,
"opt_out" : (int) the number of opt outs,
"help" : (int) the number of help messages received
}
],
... (more channels)
}
},
... (more steps)
}
},
... (more stats by time)
]
},
"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 time series. | `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_series` 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_series_get_canvas_analytics
tags:
- Export
responses:
'200':
description: The request succeeded and the response body includes the Canvas time series.
content:
application/json:
schema:
$ref: '#/components/schemas/CanvasAnalyticsResponse'
'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: Date on which the data export should end. Defaults to time of the request.
schema:
type: string
- name: starting_at
in: query
required: false
description: Date on which the data export should begin. * Either `length` or `starting_at` is required.
schema:
type: string
- name: length
in: query
required: false
description: Maximum number of days before `ending_at` to include 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 or not to include variant statistics (defaults to `false`).
schema:
type: boolean
- name: include_step_breakdown
in: query
required: false
description: Whether or not to include step statistics (defaults to `false`).
schema:
type: boolean
- name: include_deleted_step_data
in: query
required: false
description: Whether or not to include step statistics for deleted steps (defaults to `false`).
schema:
type: boolean
components:
schemas:
CanvasAnalyticsResponse:
type: object
properties:
data:
type: object
properties:
name:
type: string
description: The Canvas name.
stats:
type: array
items:
type: object
properties:
time:
type: string
description: The date as ISO 8601 date.
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 variant.
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.
step_stats:
type: object
properties:
00000000-0000-0000-0000-0000000000000:
type: object
properties:
name:
type: string
description: The name of 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:
email:
type: array
items:
type: object
properties:
sent:
type: integer
description: The number of sends.
opens:
type: integer
description: The number of opens.
unique_opens:
type: integer
description: The number of unique opens.
clicks:
type: integer
description: The number of clicks.
sms:
type: array
items:
type: object
properties:
sent:
type: integer
description: The number of sends.
sent_to_carrier:
type: integer
description: The number of messages sent to the carrier.
delivered:
type: integer
description: The number of delivered messages.
rejected:
type: integer
description: The number of rejected messages.
delivery_failed:
type: integer
description: The number of failed deliveries.
clicks:
type: integer
description: The number of clicks on shortened links.
opt_out:
type: integer
description: The number of opt outs.
help:
type: integer
description: The number of help messages received.
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