# Releases

The Releases tab lets you see **what version of your application introduced a specific error**. This is crucial for understanding when bugs were introduced and for quickly identifying the impact of new deployments.

## How a release gets created

* Every event your SDK sends carries its release version. When Better Stack sees a version it
  doesn't know yet, it creates the release automatically. This needs no setup, though the
  release only appears once the first error from that version arrives.
* You can also report a release from your build. It then appears as soon as it ships rather
  than waiting for an error, and it can record the environment it was deployed to.
* Releases are identified by a version number or reference (e.g., "v1.2.3").
* Each release tracks when it was first and last seen.
* Errors are automatically associated with the release in which they occurred.

## Report a release during your build

Better Stack accepts release reports through its [Releases API](https://betterstack.com/docs/errors/api/releases/create/), the Sentry CLI, and the Sentry bundler plugins.

[code-tabs]
```bash
[label cURL]
curl --request POST \
  --url https://errors.betterstack.com/api/v1/releases \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data "{\"version\": \"$VERSION\", \"applications\": [\"$APPLICATION_ID\"], \"environment\": \"production\"}"
```
```bash
[label Sentry CLI]
sentry-cli releases new "$VERSION"
sentry-cli releases deploys "$VERSION" new --env production
```
```javascript
[label Vite]
sentryVitePlugin({
  org: $SENTRY_ORG,
  project: $SENTRY_PROJECT,
  url: $SENTRY_URL,
  authToken: process.env.BETTER_STACK_API_TOKEN,
  release: {
    name: process.env.GIT_COMMIT_SHA,
    deploy: { env: 'production' },
  },
})
```
[/code-tabs]

For the Sentry CLI and the bundler plugins, set these from **Errors** -> Applications -> your
application -> **Advanced settings**, the same values you use for source maps:

* `SENTRY_ORG` - a Better Stack ID representing your team.
* `SENTRY_PROJECT` - the Better Stack ID for your [application](https://errors.betterstack.com/team/t0/applications/ ";_blank"). 
* `SENTRY_URL` - the Better Stack endpoint, for example `https://us-east-9-sourcemaps.betterstackdata.com`.
* `SENTRY_AUTH_TOKEN` - a [Telemetry API token](https://betterstack.com/settings/api-tokens/0 ";_blank").

The cURL request authenticates with a [Telemetry API token](https://betterstack.com/docs/errors/api/getting-api-token/) and
names the [application](https://errors.betterstack.com/team/t0/applications/ ";_blank") the release
belongs to. When `applications` is omitted, the request only attaches the environment to
applications already reporting that version, so a new release needs it. A release registered by
mistake can be [removed via the API](https://betterstack.com/docs/errors/api/releases/delete/).

## Exploring releases

![CleanShot 2025-11-07 at 5 .32.18.png](https://imagedelivery.net/xZXo0QFi-1_4Zimer-T0XQ/cd660602-558c-4656-3edc-2bce6bc0d900/md2x =2120x1102)

* View a paginated list of all releases in **Errors** -> [Releases](https://errors.betterstack.com/team/0/releases/ ";_blank").
* Filter releases by date range for historical analysis.
* Click a release to see its detail page, which includes:
    * An error **frequency histogram** for that specific release.
    * A list of **all exceptions that occurred in that release**.
    * Environment information showing where that release ran.
* Navigate back to the main errors list, filtered for a specific release.
* See breadcrumbs showing the release context within error details.

## Release markers on dashboards

When a dashboard chart is built from a source that an Errors application is correlated with, that application's releases appear as vertical dashed lines on the chart. Use them to see whether a change in your metrics lines up with a deployment.

* Markers show on line and bar timeseries charts, both on dashboards and on the single-chart view.
* They appear automatically once the correlation exists, with nothing to configure.
* Hover a marker to see a card with the release reference, application, and time. When the marker is a single release, its label links to the release detail page.
* When several releases fall close together, their labels group into a single label such as "3 releases" and split apart as you zoom in.
* Markers are visible only to members with access to Errors, and never appear on shared or public dashboards.