--- openapi: 3.0.3 info: title: Braze REST API – Export app session by time description: | ## Prerequisites To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key-permissions) with the `sessions.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: "/sessions/data_series": get: summary: Export app session by time operationId: get_sessions_data_series_get_sessions_analytics parameters: - 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: 14 - 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: day - name: ending_at in: query required: false description: | Date on which the data series should end. Defaults to time of the request. Provide an [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) datetime string. schema: type: string format: date-time example: "2018-06-28T23: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 sessions 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 app session by time. content: application/json: schema: $ref: '#/components/schemas/SessionsAnalyticsResponse' examples: success: summary: Daily sessions series value: message: success data: - time: "2018-06-27" sessions: 1180 - time: "2018-06-28" sessions: 1243 "400": description: | Bad request. To resolve 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. - **The `segment_id`, if included, isn't a valid segment API identifier:** Pass a valid `segment_id`, or omit it. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: length_missing: 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 value isn't a valid app API key value: message: app_id must be a valid app api key for this app group invalid_segment_id: summary: The segment_id value isn't a valid segment API identifier value: message: segment_id must be a string that is a valid segment api identifier "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 `sessions.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 `sessions.data_series` permission. Pass the key as `Authorization: Bearer YOUR_REST_API_KEY`. schemas: SessionsAnalyticsResponse: title: Export app session by time response type: object properties: message: type: string description: Returns 'success' when the request completes without errors. example: success data: type: array items: title: Sessions data point type: object properties: time: type: string description: Point in time - as ISO 8601 extended when unit is "hour" and as ISO 8601 date when unit is "day". example: "2018-06-28" sessions: type: integer description: The number of sessions in the time period. example: 1243 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.