v53

latestSwagger 2.0Open Government Licence v3.0raw.githubusercontent.com2026-08-053554106.9 KB

Private

Get an instance

Get the current state of an instance, this includes all events which have happened.

get/instances/{instance_id}

Path parameters

instance_idstring required

A unique id for an instance

Headers

If-Matchstring

Filter resource version, as returned by a previous ETag, to be validated; or '*' to skip the version check

Response

Return a single instance state

idstring

A unique id for an instance

collection_idstring

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

editionstring

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.

headersstring[]

The header information from a V4 file

last_updatedstring

The last time an event happened

release_datestring date-time

The release date of this version of the dataset

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

total_observationsinteger

The number of observations in this instance

versioninteger

The dataset version number that this instance is associated with, this will only be set once the state has been updated to edition-confirmed

Example response

{
  "alerts": [
    {
      "description": "This is a description of the changes made as part of the correction or other important notice about this version.",
      "type": "correction"
    }
  ],
  "collection_id": "666c06bc09d337ab9d164c82f8f383c081a4e38cbd91b79d4a23ea0025fecb3f",
  "downloads": {
    "csv": {
      "href": "https://download.ons.gov.uk/my-dataset-download.csv",
      "size": "466807"
    },
    "xls": {
      "href": "https://download.ons.gov.uk/my-dataset-download.csv",
      "size": "466807"
    }
  },
  "edition": "july-september-2017",
  "links": {
    "dataset": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset",
      "id": "my-dataset"
    },
    "dimensions": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017/versions/1/dimensions"
    },
    "edition": {
      "href": "https://api.beta.ons.gov.uk/v1/datasets/my-dataset/editions/july-september-2017",
      "id": "july-september-2017"
    },
    "job": {
      "href": "https://api.beta.ons.gov.uk/v1/jobs/042e216a-7822-4fa0-a3d6-e3f5248ffc35",
      "id": "042e216a-7822-4fa0-a3d6-e3f5248ffc35"
    },
    "self": {
      "href": "https://api.beta.ons.gov.uk/v1/instances/45c4669b-3ae9-4ba7-b690-87e890a1c67f"
    },
    "version": {
      "href": "https://api.beta.ons.gov.uk/v1/dataset/my-dataset/edition/july-september-2017/versions/1",
      "id": "1"
    }
  },
  "state": "published"
}