--- openapi: 3.0.3 info: title: Braze REST API – Export segment analytics description: 'Use this endpoint to retrieve a daily series of the estimated size of a segment over time.

If you need the exact size of a segment, export its users with the [`/users/export/segment` endpoint]({{site.baseurl}}/api/endpoints/export/user_data/post_users_segment/) and count the exported profiles. ' 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: "/segments/data_series": get: summary: Export segment analytics description: | ## Prerequisites To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key-permissions) with the `segments.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 | | --------- | -------- | --------- | ----------- | | `segment_id` | Required | String | See [Segment API identifier]({{site.baseurl}}/api/identifier_types/).

The `segment_id` for a given segment can be found on the [API Keys]({{site.baseurl}}/user_guide/administer/global/workspace_settings/apis_and_identifiers/) page within your Braze account or you can use the [Export segment list endpoint]({{site.baseurl}}/api/endpoints/export/segments/get_segment/). | | `length` | Required | Integer | Maximum number of days before `ending_at` to include in the returned series. Must be between 1 and 100 (inclusive). | | `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. | ## Example request The following sample request shows an example of how to export segment analytics. ``` curl --location -g --request GET 'https://rest.iad-01.braze.com/segments/data_series?segment_id={{segment_identifier}}&length=14&ending_at=2018-06-27T23:59:59-5:00' \ --header 'Authorization: Bearer YOUR_REST_API_KEY' ``` ## Response The following sample response shows an example of the response returned when you export segment analytics. ```json { "message": (string) returns 'success' when the request completes without errors, "data" : [ { "time" : (string) the date as ISO 8601 date, "size" : (int) the size of the segment on that date }, ... ] } ``` ## 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 `segment_id` is missing or 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`. Find it with the [Export segment list endpoint]({{site.baseurl}}/api/endpoints/export/segments/get_segment/). | | `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 `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. | | `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 `segments.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_segments_data_series_get_segment_analytics tags: - Export responses: '200': description: The request succeeded and the response body includes the requested data. content: application/json: schema: $ref: '#/components/schemas/SegmentAnalyticsResponse' '400': description: |- Bad Request. Causes include: - `segment_id must be a string that is a valid segment api identifier` — The `segment_id` is missing or isn't a valid segment API identifier. - The `length` is missing, isn't an integer, or is out of range. - The `ending_at` value is improperly formatted or out of range. 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: segment_id in: query required: true description: See Segment API identifier. The `segment_id` for a given segment can be found on the API Keys page within your Braze account or you can use the Export segment list endpoint. schema: type: string - name: length in: query required: true description: Maximum number of days before `ending_at` to include in the returned series. Must be between 1 and 100 (inclusive). schema: type: integer - 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 components: schemas: SegmentAnalyticsResponse: 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 date as ISO 8601 date. size: type: integer description: The size of the segment on that date. 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