---
openapi: 3.0.3
info:
title: Braze REST API – Export custom events analytics
description: 'Use this endpoint to retrieve a series of the number of occurrences of a custom event in your app over a designated time period.
'
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:
"/events/data_series":
get:
summary: Export custom events analytics
description: |
## Prerequisites
To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key-permissions) with the `events.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 |
| -------- | -------- | --------- | ----------- |
| `event` | Required | String | The name of the custom event for which to return analytics. |
| `length` | Required | Integer | Maximum number of units (days or hours) before `ending_at` to include in the returned series. Must be between 1 and 100 (inclusive). |
| `unit` | Optional | String | Unit of time between data points. Can be `day` or `hour`, defaults to `day`. |
| `ending_at` | Optional | Datetime
([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | Date on which the data series should end. Defaults to time of the request. |
| `app_id` | Optional | String | App API identifier retrieved from the [API Keys]({{site.baseurl}}/user_guide/administer/global/workspace_settings/apis_and_identifiers/) page to limit analytics to a specific app. |
| `segment_id` | Optional | String | See [Segment API identifier]({{site.baseurl}}/api/identifier_types/). Segment ID indicating the analytics-enabled segment for which event analytics should be returned. |
## Example request
The following sample request shows an example of how to export custom events analytics.
```
curl --location -g --request GET 'https://rest.iad-01.braze.com/events/data_series?event=event_name&length=24&unit=hour&ending_at=2014-12-10T23:59:59-05:00&app_id={{app_identifier}}&segment_id={{segment_identifier}}' \
--header 'Authorization: Bearer YOUR_REST_API_KEY'
```
## Response
The following sample response shows an example of the response returned when you export custom events analytics.
```json
{
"message": (string) returns 'success' when the request completes without errors,
"data" : [
{
"time" : (string) the point in time - as ISO 8601 extended when unit is "hour" and as ISO 8601 date when unit is "day",
"count" : (int) the number of occurrences of provided custom event
},
...
]
}
```
### Fatal error response codes {#fatal-export}
For status codes and associated error messages that will be returned if your request encounters a fatal error, reference [Fatal errors & responses]({{site.baseurl}}/api/errors/#fatal-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 requested data. | `success` | No action needed. |
| `400 Bad Request` | The `event` value isn't the name of a custom event. | `'event' must be the name of a custom event` | Pass the exact name of a custom event recorded for your workspace. |
| `400 Bad Request` | The `segment_id`, if included, isn't a valid segment API identifier. | `segment_id must be a string that is a valid segment api identifier` | Pass a valid `segment_id`, or omit it. |
| `400 Bad Request` | The `length` is missing, isn't an integer, or is out of range. | `an integer length must be provided`
`series range must be greater than 0 and less than 100` | Pass an integer `length` between 1 and 100. |
| `400 Bad Request` | The `unit` value isn't `day` or `hour`. | `allowed values for unit are 'hour' and 'day'` | Set `unit` to `day` or `hour`. |
| `400 Bad Request` | The `ending_at` value is improperly formatted or out of range. | `ending_at time is improperly formatted`
`ending_at time is out of range` | Provide `ending_at` as an ISO-8601 datetime that isn't in the future or before the year 2000. |
| `400 Bad Request` | The `app_id` value isn't a valid app API key for this workspace. | `app_id must be a valid app api key for this app group` | Pass a valid `app_id` from the API Keys page, or omit it. |
| `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 `events.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_events_data_series_get_custom_events_analytics
tags:
- Export
responses:
'200':
description: The request succeeded and the response body includes the requested data.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomEventsAnalyticsResponse'
'400':
description: |-
Bad Request. Causes include:
- `'event' must be the name of a custom event` — The `event` value isn't the name of a custom event.
- `segment_id must be a string that is a valid segment api identifier` — The `segment_id`, if included, isn't a valid segment API identifier.
- The `length` is missing, isn't an integer, or is out of range.
- `allowed values for unit are 'hour' and 'day'` — The `unit` value isn't `day` or `hour`.
- The `ending_at` value is improperly formatted or out of range.
- `app_id must be a valid app api key for this app group` — The `app_id` value isn't a valid app API key for this workspace.
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: event
in: query
required: true
description: The name of the custom event for which to return analytics.
schema:
type: string
- name: length
in: query
required: true
description: Maximum number of units (days or hours) before `ending_at` to include in the returned series. Must be between 1 and 100 (inclusive).
schema:
type: integer
- name: unit
in: query
required: false
description: Unit of time between data points. Can be `day` or `hour`, defaults to `day`.
schema:
type: string
- name: ending_at
in: query
required: false
description: Date on which the data series should end. Defaults to time of the request.
schema:
type: string
- name: app_id
in: query
required: false
description: App API identifier retrieved from the API Keys page to limit analytics to a specific app.
schema:
type: string
- name: segment_id
in: query
required: false
description: See Segment API identifier. Segment ID indicating the analytics-enabled segment for which event analytics should be returned.
schema:
type: string
components:
schemas:
CustomEventsAnalyticsResponse:
type: object
properties:
message:
type: string
description: Returns 'success' when the request completes without errors.
data:
type: array
items:
type: object
properties:
time:
type: string
description: The point in time - as ISO 8601 extended when unit is "hour" and as ISO 8601 date when unit is "day".
count:
type: integer
description: The number of occurrences of provided custom event.
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