---
openapi: 3.0.3
info:
  title: Braze REST API – 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/).
  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: |
        ## Fatal error response codes

        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).
      operationId: get_events_data_series_get_custom_events_analytics
      parameters:
        - name: event
          in: query
          required: true
          description: The name of the custom event for which to return analytics.
          schema:
            type: string
          example: event_name
        - 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
            minimum: 1
            maximum: 100
          example: 24
        - name: unit
          in: query
          required: false
          description: Unit of time between data points. Can be `day` or `hour`, defaults to `day`.
          schema:
            type: string
            enum: [day, hour]
            default: day
          example: hour
        - name: ending_at
          in: query
          required: false
          description: |
            Date on which the data series should end. Defaults to time of the request.

            Format: [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) datetime string.
          schema:
            type: string
            format: date-time
          example: "2014-12-10T23:59:59-05:00"
        - name: app_id
          in: query
          required: false
          description: 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.
          schema:
            type: string
          example: "{{app_identifier}}"
        - name: segment_id
          in: query
          required: false
          description: See [Segment API identifier]({{site.baseurl}}/api/identifier_types/). Segment ID indicating the analytics-enabled segment for which event analytics should be returned.
          schema:
            type: string
          example: "{{segment_identifier}}"
      responses:
        "200":
          description: |
            The request succeeded and the response body includes the requested data. No action needed.

            The following sample response shows an example of the response returned when you export custom events analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomEventsAnalyticsResponse'
              examples:
                hourly:
                  summary: Hourly data series
                  value:
                    message: success
                    data:
                      - time: "2014-12-10T22:00:00-05:00"
                        count: 42
                      - time: "2014-12-10T23:00:00-05:00"
                        count: 17
        "400":
          description: |
            Bad request. To resolve it:

            - **The `event` value isn't the name of a custom event:** Pass the exact name of a custom event recorded for your workspace.
            - **The `segment_id`, if included, isn't a valid segment API identifier:** Pass a valid `segment_id`, or omit it.
            - **The `length` is missing, isn't an integer, or is out of range:** Pass an integer `length` between 1 and 100.
            - **The `unit` value isn't `day` or `hour`:** Set `unit` to `day` or `hour`.
            - **The `ending_at` value is improperly formatted or out of range:** Provide `ending_at` as an ISO-8601 datetime that isn't in the future or before the year 2000.
            - **The `app_id` value isn't a valid app API key for this workspace:** Pass a valid `app_id` from the API Keys page, or omit it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_event:
                  summary: The event value isn't the name of a custom event
                  value:
                    message: "'event' must be the name of a custom event"
                invalid_segment_id:
                  summary: The segment_id isn't a valid segment API identifier
                  value:
                    message: segment_id must be a string that is a valid segment api identifier
                missing_length:
                  summary: The length is missing or isn't an integer
                  value:
                    message: an integer length must be provided
                length_out_of_range:
                  summary: The length is out of range
                  value:
                    message: series range must be greater than 0 and less than 100
                invalid_unit:
                  summary: The unit value isn't day or hour
                  value:
                    message: allowed values for unit are 'hour' and 'day'
                ending_at_improperly_formatted:
                  summary: The ending_at value is improperly formatted
                  value:
                    message: ending_at time is improperly formatted
                ending_at_out_of_range:
                  summary: The ending_at value is out of range
                  value:
                    message: ending_at time is out of range
                invalid_app_id:
                  summary: The app_id isn't a valid app API key
                  value:
                    message: app_id must be a valid app api key for this app group
        "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 `events.data_series` 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 `events.data_series` permission.
        Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`.
  schemas:
    CustomEventDataPoint:
      title: Custom event data point
      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".
          example: "2014-12-10T23:00:00-05:00"
        count:
          type: integer
          description: The number of occurrences of provided custom event.
          example: 17
    CustomEventsAnalyticsResponse:
      title: Export custom events analytics response
      type: object
      properties:
        message:
          type: string
          description: Returns 'success' when the request completes without errors.
          example: success
        data:
          type: array
          items:
            $ref: '#/components/schemas/CustomEventDataPoint'
    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.