Export Canvas data summary analytics

get

/canvas/data_summary

Use this endpoint to export rollups of time series data for a Canvas, providing a concise summary of Canvas results.

See me in Postman

Prerequisites

To use this endpoint, you’ll need an 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.

Request parameters

Parameter	Required	Data Type	Description
`canvas_id`	Required	String	See Canvas API identifier.
`ending_at`	Required	Datetime (ISO-8601 string)	End date for the data export. Defaults to the time of the request.
`starting_at`	Optional*	Datetime (ISO-8601 string)	Start date for the data export. * Either `length` or `starting_at` is required.
`length`	Optional*	String	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

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

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

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.

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 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 for the ` /campaigns/data_series endpoint. Where present, fields ending in _by_entry_time` attribute those conversions by Canvas entry time.

{
  "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": (required, string) the status of the export, returns 'success' on successful completion
}