VersionHistory API reference

Published on

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
NameDescription
productA product identifier.
platformA platform identifier.
channelA 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
NameDescription
productA product identifier.
platformA platform identifier.
channelA channel identifier.
versionA version identifier.

Product

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

Product identifiers

DescriptionValue
Chromechrome
Fuchsia Web Enginefuchsiawebengine

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
NameDescription
productA product identifier.

Get all platform and channel combinations

GET /{product}/platforms/all/channels
NameDescription
productA product identifier.

Platform identifiers

DescriptionValue
All platformsall
Windowswin
Windows (64-bit)win64
Macmac
Mac (ARM64)mac_arm64
Linuxlinux
Androidandroid
WebViewwebview
iOSios
Lacroslacros

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
NameDescription
productA product identifier.
platformA platform identifier.

Channel identifiers

The VersionHistory API supports the following channel identifiers:

DescriptionValue
Extended Stableextended
Stablestable
Betabeta
Devdev
Canarycanary
Canary (variant build)canary_asan

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 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.

ItemValid values
Fieldversion, name, platform, starttime*, endtime*, fraction*
Operator<, <=, =, >, >=

An item with an asterisk (*) to the right of it is only valid for 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 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.

Last updated: Improve article

We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.