sentry/api-docs/paths/releases/sessions.json

{
  "get": {
    "tags": ["Releases"],
    "description": "Returns a time series of release health session statistics for projects bound to an organization.\n\nThe interval and date range are subject to certain restrictions and rounding rules.\n\nThe date range is rounded to align with the interval, and is rounded to at least one hour. The interval can at most be one day and at least one hour currently. It has to cleanly divide one day, for rounding reasons.\n\nApart from the query parameters listed below, this endpoint also supports the usual [pagination parameters](https://docs.sentry.io/api/pagination/).",
    "operationId": "Retrieve Release Health Session Statistics",
    "parameters": [
      {
        "name": "organization_slug",
        "in": "path",
        "description": "The slug of the organization.",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      {
        "name": "project",
        "in": "query",
        "description": "The ID of the projects to filter by.\n\nUse `-1` to include all accessible projects.",
        "required": true,
        "schema": {
          "type": "array",
          "items": {
            "type": "integer"
          }
        },
        "style": "form",
        "explode": true
      },
      {
        "name": "field",
        "in": "query",
        "description": "The list of fields to query.\n\nThe available fields are\n  - `sum(session)`\n  - `count_unique(user)`\n  - `avg`, `p50`, `p75`, `p90`, `p95`, `p99`, `max` applied to `session.duration`. For example, `p99(session.duration)`. Session duration is [no longer being recorded](https://github.com/getsentry/sentry/discussions/42716) as of on Jan 12, 2023. Returned data may be incomplete.\n  - `crash_rate`, `crash_free_rate` applied to `user` or `session`. For example, `crash_free_rate(user)`",
        "required": true,
        "schema": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "style": "form",
        "explode": true
      },
      {
        "name": "environment",
        "in": "query",
        "description": "The name of environments to filter by.",
        "required": false,
        "schema": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "style": "form",
        "explode": true
      },
      {
        "name": "groupBy",
        "in": "query",
        "description": "The list of properties to group by.\n\nThe available groupBy conditions are `project`, `release`, `environment` and `session.status`.\n\nGrouping by `session.status` does not work when `crash_rate` or `crash_free_rate` are queried.",
        "required": false,
        "schema": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "style": "form",
        "explode": true
      },
      {
        "name": "orderBy",
        "in": "query",
        "description": "An optional field to order by, which must be one of the fields provided in `field`. Use `-` for descending order, for example `-sum(session)`. \n\nThis alters the order of the `groups` returned, so it only makes sense in combination with `groupBy`. \n\nOrdering by more than one field is currently not supported.",
        "required": false,
        "schema": {
          "type": "string"
        }
      },
      {
        "name": "query",
        "in": "query",
        "description": "A free-form query that is applied as a filter.\n\nAn example query could be `release:\"1.1.0\" or release:\"1.2.0\"`.",
        "required": false,
        "schema": {
          "type": "string"
        }
      },
      {
        "name": "statsPeriod",
        "in": "query",
        "description": "This defines the range of the time series, relative to now.\n\nThe range is given in a `\"<number><unit>\"` format.\n\nFor example `1d` for a one day range. Possible units are `m` for minutes, `h` for hours, `d` for days and `w` for weeks.\n\nIt defaults to `90d`.",
        "required": false,
        "schema": {"type": "string"}
      },
      {
        "name": "interval",
        "in": "query",
        "description": "This is the resolution of the time series, given in the same format as `statsPeriod`.\n\nThe default resolution is `1h` and the minimum resolution is currently restricted to `1h` as well.\n\nIntervals larger than `1d` are not supported, and the interval has to cleanly divide one day.",
        "required": false,
        "schema": {"type": "string"}
      },
      {
        "name": "statsPeriodStart",
        "in": "query",
        "description": "This defines the start of the time series range, in the same format as the `interval`, relative to now.",
        "required": false,
        "schema": {"type": "string"}
      },
      {
        "name": "statsPeriodEnd",
        "in": "query",
        "description": "This defines the end of the time series range, in the same format as the `interval`, relative to now.",
        "required": false,
        "schema": {"type": "string"}
      },
      {
        "name": "start",
        "in": "query",
        "description": "This defines the start of the time series range as an explicit datetime.",
        "required": false,
        "schema": {"type": "string", "format": "date-time"}
      },
      {
        "name": "end",
        "in": "query",
        "description": "This defines the inclusive end of the time series range as an explicit datetime.",
        "required": false,
        "schema": {"type": "string", "format": "date-time"}
      }
    ],
    "responses": {
      "200": {
        "description": "Time-series Session Statistics.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "../../components/schemas/sessions.json#/Sessions"
            },
            "example": {
              "start": "2021-02-01T00:00:00Z",
              "end": "2021-02-04T00:00:00Z",
              "intervals": [
                "2021-02-01T00:00:00Z",
                "2021-02-02T00:00:00Z",
                "2021-02-03T00:00:00Z"
              ],
              "groups": [
                {
                  "by": {"session.status": "healthy"},
                  "totals": {"sum(session)": 1715553},
                  "series": {"sum(session)": [683772, 677788, 353993]}
                },
                {
                  "by": {"session.status": "abnormal"},
                  "totals": {"sum(session)": 0},
                  "series": {"sum(session)": [0, 0, 0]}
                },
                {
                  "by": {"session.status": "crashed"},
                  "totals": {"sum(session)": 383},
                  "series": {"sum(session)": [33, 26, 324]}
                },
                {
                  "by": {"session.status": "errored"},
                  "totals": {"sum(session)": 1565},
                  "series": {"sum(session)": [163, 201, 1201]}
                }
              ]
            }
          }
        }
      },
      "400": {
        "description": "Wrong Parameters",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "../../components/schemas/error.json#/ApiError"
            }
          }
        }
      },
      "401": {
        "description": "Unauthorized"
      },
      "403": {
        "description": "Forbidden"
      }
    },
    "security": [
      {
        "auth_token": ["org: read"]
      }
    ]
  }
}