This page contains technical reference information about the VersionHistory web
service API.

All API access is over HTTPS, and accessed from `https://versionhistory.googleapis.com/v1`.

## Version

A version is a particular instance of Chrome that users are running.

### Get version information for a given platform and channel

Lists all Chrome versions for the given platform and channel.

```console
GET /{product}/platforms/{platform}/channels/{channel}/versions
```

| Name | Description |
|---|---|
| `product` | A [product identifier](https://developer.chrome.com/docs/web-platform/versionhistory/reference.md.txt#product-identifiers). |
| `platform` | A [platform identifier](https://developer.chrome.com/docs/web-platform/versionhistory/reference.md.txt#platform-identifiers). |
| `channel` | A [channel identifier](https://developer.chrome.com/docs/web-platform/versionhistory/reference.md.txt#channel-identifiers). |

## Release

A release is the interval in which users were running a particular
version of Chrome. The release endpoints also provide information
around what fraction of users were running that version of Chrome
during that interval.

### Get all releases

Lists all releases for the given platform, channel, and version.

```console
GET /{product}/platforms/{platform}/channels/{channel}/versions/{version}/releases
```

| Name | Description |
|---|---|
| `product` | A [product identifier](https://developer.chrome.com/docs/web-platform/versionhistory/reference.md.txt#product-identifiers). |
| `platform` | A [platform identifier](https://developer.chrome.com/docs/web-platform/versionhistory/reference.md.txt#platform-identifiers). |
| `channel` | A [channel identifier](https://developer.chrome.com/docs/web-platform/versionhistory/reference.md.txt#channel-identifiers). |
| `version` | A version identifier. |

## Product

A product is piece of software such as Chrome or Fuchsia Web Engine.

### Product identifiers

| Description | Value |
|---|---|
| Chrome | `chrome` |
| Fuchsia Web Engine | `fuchsiawebengine` |

## Platform

A platform is one of the computing platforms that a product runs on, such
as Windows, Android, etc.

### Get all platforms

```console
GET /{product}/platforms
```

| Name | Description |
|---|---|
| `product` | A [product identifier](https://developer.chrome.com/docs/web-platform/versionhistory/reference.md.txt#product-identifiers). |

### Get all platform and channel combinations

```console
GET /{product}/platforms/all/channels
```

| Name | Description |
|---|---|
| `product` | A [product identifier](https://developer.chrome.com/docs/web-platform/versionhistory/reference.md.txt#product-identifiers). |

### Platform identifiers

| Description | Value |
|---|---|
| All platforms | `all` |
| Windows | `win` |
| Windows (64-bit) | `win64` |
| Mac | `mac` |
| Mac (ARM64) | `mac_arm64` |
| Linux | `linux` |
| Android | `android` |
| WebView | `webview` |
| iOS | `ios` |
| Lacros | `lacros` |

## Channel

See [How do I choose which channel to use?](https://www.chromium.org/getting-involved/dev-channel#TOC-How-do-I-choose-which-channel-to-use-) for an explanation
of Chrome's channels.

### Get a platform's valid channels

Lists the valid channels for a given platform:

```console
GET /{product}/platforms/{platform}/channels
```

| Name | Description |
|---|---|
| `product` | A [product identifier](https://developer.chrome.com/docs/web-platform/versionhistory/reference.md.txt#product-identifiers). |
| `platform` | A [platform identifier](https://developer.chrome.com/docs/web-platform/versionhistory/reference.md.txt#platform-identifiers). |

### Channel identifiers

The VersionHistory API supports the following channel identifiers:

| Description | Value |
|---|---|
| Extended Stable | `extended` |
| Stable | `stable` |
| Beta | `beta` |
| Dev | `dev` |
| Canary | `canary` |
| Canary (variant build) | `canary_asan` |

> [!NOTE]
> **Note:** `canary_asan` is a fraction of the Canary population that receives a variant build of Chrome. This variant build has more diagnostics capabilities enabled which makes it better at uncovering bugs.

## Filter results

Add a `filter` query parameter to filter results. Only the
[version](https://developer.chrome.com/docs/web-platform/versionhistory/reference.md.txt#version) and [release](https://developer.chrome.com/docs/web-platform/versionhistory/reference.md.txt#release) endpoints support filtering.
Example:

```console
GET /chrome/platforms/win/channels/stable/versions/all/releases?filter=fraction=1
```

The value of `filter` should be a comma-separated list of expressions. Each
expression should take the form of `field operator value`.

| Item | Valid values |
|---|---|
| Field | `version`, `name`, `platform`, `starttime`\*, `endtime`\*, `fraction`\* |
| Operator | `<`, `<=`, `=`, `>`, `>=` |

> [!NOTE]
> **Note:** An item with an asterisk (`*`) to the right of it is only valid for [release](https://developer.chrome.com/docs/web-platform/versionhistory/reference.md.txt#release) endpoints.

- Channel filtering is done by distance from Stable, in other words `stable` \< `beta` \< `dev` \< `canary` \< `canary_asan`. For example, `channel<=dev` returns information for `stable`, `beta`, and `dev`.
- Version filtering is done numerically, for example `1.0.0.8` \< `1.0.0.10`. If a version is not entirely written, VersionHistory appends `0` for the missing fields. For example, `version>80` becomes `version>80.0.0.0`.
- `endtime=none` filters for releases that are currently live and do not have an end time yet.
- When filtering by `starttime` or `endtime`, the value must be in [RFC 3339](https://medium.com/easyread/understanding-about-rfc-3339-for-datetime-formatting-in-software-engineering-940aa5d5f68a) date string format.
- `name` and `platform` are filtered by string comparison.
- `fraction` is used to specify how many users were involved in the rollout. For example, `fraction=1` means 100% of users.

## Order results

Add a `order_by` query parameter to order results. Only the
[version](https://developer.chrome.com/docs/web-platform/versionhistory/reference.md.txt#version) and [release](https://developer.chrome.com/docs/web-platform/versionhistory/reference.md.txt#release) endpoints support ordering.
Example:

```console
GET /chrome/platforms/win/channels/stable/versions/all/releases?order_by=starttime
```

`order_by` accepts a comma-separated list of the following
values: `version`, `name`, `platform`, `channel`, `starttime`,
`endtime`, `fraction`.

Add a space character (`%20`) followed by `asc` or `desc` after the `order_by` value to specify ascending
or descending ordering. Example:

```console
GET /chrome/platforms/win/channels/stable/versions/all/releases?order_by=starttime%20asc
```

- Channel ordering is done in the following order: `stable`, `beta`, `dev`, `canary`, `canary_asan`.
- Ordering by `name` may cause unexpected behaviour as it is a naive string sort. For example, `1.0.0.8` will be before 1.0.0.10 in descending order.
- When `order_by` is not specified the default ordering is by `platform`, `channel`, `version`, and then `serving.starttime`.