---
title: "List the edition's version history"
method: GET
path: "/datasets/{id}/editions/{edition}/versions"
tags: ["Public"]
---

# List the edition's version history

`GET /datasets/{id}/editions/{edition}/versions`

## Request

- Base URL: `https://api.beta.ons.gov.uk/v1`
- URL: `https://api.beta.ons.gov.uk/v1/datasets/{id}/editions/{edition}/versions`
- Auth: one of:
  - none
  - API key in header `Authorization`
  - API key in header `Authorization` and API key in header `X-Download-Service-Token`

Get a list of all versions for a dataset edition.

## Path parameters

- `edition` string, required
- `id` string, required

## Query parameters

- `limit` integer
- `offset` integer

## Response `200`

A json list containing all versions for a set type of dataset and edition

- Versions: A list of version history for a specific dataset edition.
  - `count` integer: The number of items returned.
  - `limit` integer: The number of items requested.
  - `offset` integer: The offset of the first item to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter
  - `total_count` integer: The total number of items available.
  - `items` Version[]
    - `alerts` Alert[]: A list of alerts, for example corrections after the resource has been published
      - `date` string, date-time, required: The date and time of publication of the version
      - `description` string, required: Detail of what a user needs to be aware of for this dataset
      - `type` 'alert' | 'correction', required: The type of alert. Available types: * `alert`: Important contextual information relevant to the interpretation of a specific version of the dataset. * `correction`: A correction notice summarising the data changes made in the corrected as compared to the superseded version.
    - `collection_id` string: **Internal Only: This is an internal only field and is not present once a dataset is published.** The id of the unpublished collection (of datasets) that this dataset is associated with."
    - `dataset_id` string: The unique identifier for a dataset. The dataset ID cannot be changed once the series is first published.
    - `dimensions` Dimension[]: A list of codelists for each dimension of this version
      - `description` string
      - `dimension` string: The name of the dimension
      - `href` string: A link to the code-list entry for the dimension
      - `id` string: The id of the dimension
      - `is_area_type` boolean: Indicates if a dimension is an area-type (census datasets only)
      - `label` string
      - `links` object
        - `code_list` object: The code list related to this dimension
          - `href` string: A URL to the code list
          - `id` string: The unique id for the code list
        - `options` OptionsLink: A list of links related to this dimension
          - `href` string: A URL to a list of options for this dimension
        - `version` VersionLink: The dataset version this resource belongs to
          - `href` string: A URL to the version this resource relates to
          - `id` string: The version number this resource relates to
      - `number_of_options` integer: The number of options available for this dimension
      - `variable` string: The variable name (census datasets only)
    - `distributions` Distribution[], required: A list of representations of the dataset available and how to access them.
      - `title` string, required: The title or label of the distribution.
      - `download_url` string, url, required: URL to directly download a file for the distribution in the specified format.
      - `byte_size` integer: The size in bytes of the download file referenced by `download_url`.
      - `format` 'csv' | 'sdmx' | 'xls' | 'xlsx' | 'csdb', required: The format for the download file referenced by `download_url`. Formats supported: * `csv` * `sdmx` * `xls` * `xlsx` * `csdb`
      - `media_type` 'text/csv' | 'application/vnd.sdmx.structurespecificdata+xml' | 'application/vnd.ms-excel' | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' | 'text/plain': The IANA media type for the download file referenced by `download_url`. Media Types supported: * `text/csv`: CSV files * `application/vnd.sdmx.structurespecificdata+xml`: SDMX files * `application/vnd.ms-excel`: Excel (XLS) files * `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`: Excel (XLSX) files * `text/plain`: Plain text (used for CSDB output structured text files)
    - `downloads` object: **Deprecated:** These fields have been deprecated and replaced by the `distributions` list. A selection of download objects containing information of downloadable files.
      - `csv` DownloadObject: Object containing information of a downloadable file
        - `href` string: The URL to the generated file
        - `size` string: The size of the file in bytes
      - `csvw` object: Object containing information of a downloadable file
        - `href` string: The URL to the generated file
        - `size` string: The size of the file in bytes
      - `txt` object: Object containing information of a downloadable file
        - `href` string: The URL to the generated file
        - `size` string: The size of the file in bytes
      - `xls` DownloadObject: Object containing information of a downloadable file
        - `href` string: The URL to the generated file
        - `size` string: The size of the file in bytes
    - `edition` string: The unique identifier for an edition of a dataset. The edition ID cannot be changed once first published. If a subsequent version of the edition attempts to change the edition ID, they will be treated as the first version of a new edition instead.
    - `edition_title` string, required: The human readable title of the edition.
    - `is_based_on` IsBasedOn: Information about the population-type that the dataset is based on (census 2021 only)
      - `id` string: The population-type that the dataset is based on
      - `type` string: The type of the dataset
    - `is_migration` boolean: Indicates whether this version was created as part of a dataset migration
    - `last_updated` string, date-time: The date and time of the last update to the resource. For published resources this is the date and time the latest change was published.
    - `latest_changes` LatestChange[]: A list of changes between version of an edition for a dataset and the previous version of the same dataset edition
      - `description` string: A description of what has changed between versions
      - `name` string: The title of the change that has occurred between versions
    - `links` VersionLinks: A list of links related to this resource
      - `dataset` DatasetLink: An object containing the dataset id and link
        - `href` string: A URL to the parent dataset for this resource
        - `id` string: The unique identifier for a dataset. The dataset ID cannot be changed once the series is first published.
      - `dimensions` object
        - `href` string: A URL to list dimensions for this version
      - `edition` EditionLink: An object containing the edition and link
        - `href` string: A URL to the dataset edition for a version
        - `id` string: The unique id for the dataset edition for a version
      - `self` object: A link to this resource
        - `href` string: A URL to this resource
      - `web_page` object: A link to the location of this version of the dataset on the web
        - `href` string: The uri to the location of this version of the dataset on the web
      - `versions` object
        - `href` string: A URL to all versions for an edition of a dataset
    - `lowest_geography` 'oa' | 'lsoa' | 'msoa' | 'wpc' | 'ltla' | 'rgn': The lowest geography this dataset is available at (Census datasets only) Possible geographies: * `oa`: Output Areas * `lsoa`: Lower layer Super Output Areas * `msoa`: Middle layer Super Output Areas * `wpc`: Westminster Parliamentary constituencies * `ltla`: Lower Tier Local Authorities * `rgn`: Regions
    - `quality_designation` 'accredited-official' | 'official' | 'official-in-development' | 'no-accreditation': The official statistics quality designation level of this dataset version. Possible quality designations: * `accredited-official` * `official` * `official-in-development` * `no-accreditation`
    - `release_date` string, date-time, required: The release date of this version of the dataset
    - `state` 'created' | 'completed' | 'failed' | 'edition-confirmed' | 'associated' | 'published': The state of the resource, can only be one of the following: * created * completed (instances only) * failed (instances only) * edition-confirmed (instances and versions only) * associated (not editions) * published
    - `type` 'filterable' | 'cantabular_flexible_table' | 'cantabular_multivariate_table' | 'static': The type of dataset as determined by the backing data store. Used to determine which functionality is available for a dataset. Available types: * `filterable`: Datasets provided by Customise My Data product providing ability to filter observations by specific dimension options. * `cantabular_flexible_table`: Dataset derived from a `cantabular_blob` allowing the option to change the geography level and filter on specific areas. * `cantabular_multivariate_table`: Dataset with multiple variables derived from a `cantabular_blob` allowing the option to customise the dataset by adding or removing dimensions as well as by changing the geography level and dimension categorisation. * `static`: Datasets available as a flat file download without additional querying capabilities.
    - `usage_notes` UsageNote[]: A list of usage notes relating to the dataset
      - `title` string, required: The title of the usage note.
      - `note` string, required: The usage note text.
    - `version` integer: A number identifying the version for an edition from a dataset

## Other responses

- `400`: Invalid request, reasons can be one of the following: * dataset id was incorrect * edition was incorrect
- `404`: No versions found using the id and edition provided
- `500`: Failed to process the request due to an internal error

---

[API](https://skmtc.dev/office-of-national-statistics/apis/dataset-api.md) - [All operations](https://skmtc.dev/office-of-national-statistics/apis/dataset-api/llms.txt) - [OpenAPI document](https://skmtc.dev/office-of-national-statistics/apis/dataset-api/revisions/a2947a13d675?raw)