--- openapi: 3.0.3 info: title: Braze REST API – Export custom events list description: | Export the list of custom event names that have been recorded for your app. Event names are returned in groups of 250, sorted alphabetically. For status codes and error messages returned for fatal request failures, see [Fatal errors and responses](https://www.braze.com/docs/api/errors/#fatal-errors). For help with CSV and API exports, see [Export troubleshooting](https://www.braze.com/docs/user_guide/data/distribution/export_braze_data/export_troubleshooting/). 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 tags: - name: Export description: Access and export campaign, Canvas, KPI, and event data. security: - BearerAuth: [] paths: /events/list: get: summary: Export custom events list description: | Returns a paginated list of custom event names. Event names are returned in groups of 250, sorted alphabetically. Requires a REST API key with the `events.list` permission. **Rate limit:** 1,000 requests per hour, shared with `/events`, `/purchases/product_list`, and `/custom_attributes`. ## Prerequisites To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key-permissions) with the `events.list` permission. ## Rate limit We apply a shared rate limit of 1,000 requests per hour to this endpoint. This rate limit is shared with the `/custom_attributes`, `/events`, and `/purchases/product_list` endpoints, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/). ## Request parameters | Parameter| Required | Data Type | Description | | -------- | -------- | --------- | ----------- | | `page` | Optional | Integer | The page of event names to return, defaults to 0 (returns the first set of up to 250). | ## Example request ``` curl --location --request GET 'https://rest.iad-01.braze.com/events/list?page=3' \ --header 'Authorization: Bearer YOUR-REST-API-KEY' ``` ## Response ```json { "message": (string) returns 'success' when the request completes without errors, "events" : [ "Event A", (string) the event name, "Event B", (string) the event name, "Event C", (string) the event name, ... ] } ``` ### 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). **Tip:** For help with CSV and API exports, visit [Export troubleshooting]({{site.baseurl}}/user_guide/data/distribution/export_braze_data/export_troubleshooting). ## 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 lists the custom event names. | `success` | No action needed. | | `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.list` 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/). | operationId: listCustomEvents tags: - Export parameters: - name: page in: query required: false description: The page of event names to return. Defaults to 0 (the first 250). schema: type: integer minimum: 0 default: 0 example: 0 responses: "200": description: A page of custom event names. content: application/json: schema: $ref: '#/components/schemas/EventsListResponse' examples: first_page: summary: First page of events value: message: success events: - Account Created - Added Item to Cart - Completed Tutorial - Loyalty Acknowledgement - Started Subscription empty_page: summary: Page beyond the last result value: message: success events: [] "401": description: Unauthorized – the API key is missing, invalid, or lacks the `events.list` permission. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: value: message: invalid_api_key "429": description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rate_limited: value: message: rate_limited 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.list` permission. Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`. schemas: EventsListResponse: type: object required: [message, events] properties: message: type: string description: Status of the export. Returns `success` when completed without errors. example: success events: type: array description: List of custom event names on this page. items: type: string example: - Account Created - Added Item to Cart - Completed Tutorial ErrorResponse: type: object properties: message: type: string errors: type: array items: type: string