VersionHistory API reference

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.

GET /{product}/platforms/{platform}/channels/{channel}/versions
Name Description
product A product identifier.
platform A platform identifier.
channel A channel identifier.

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.

GET /{product}/platforms/{platform}/channels/{channel}/versions/{version}/releases
Name Description
product A product identifier.
platform A platform identifier.
channel A channel identifier.
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

GET /{product}/platforms
Name Description
product A product identifier.

Get all platform and channel combinations

GET /{product}/platforms/all/channels
Name Description
product A product identifier.

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? for an explanation of Chrome's channels.

Get a platform's valid channels

Lists the valid channels for a given platform:

GET /{product}/platforms/{platform}/channels
Name Description
product A product identifier.
platform A platform identifier.

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

Filter results

Add a filter query parameter to filter results. Only the version and release endpoints support filtering. Example:

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 <, <=, =, >, >=
  • 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 date string format.
  • name and platform are filtered by string comparison.
  • For releases that Chrome is still serving, serving.endtime will not be populated. During ordering or filtering, serving.endtime will be treated as 1970-01-01T00:00:00Z if the field is not populated.
  • 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 and release endpoints support ordering. Example:

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:

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.