---
title: "Get instances"
method: GET
path: "/instances"
tags: ["Private"]
---

# Get instances

`GET /instances`

## Request

- Base URL: `https://api.beta.ons.gov.uk/v1`
- URL: `https://api.beta.ons.gov.uk/v1/instances`
- Auth: API key in header `Authorization`

Get a list of instances which has been paged

## Query parameters

- `state` string
- `dataset` string
- `limit` integer
- `offset` integer

## Response `200`

Return a list of instance state

- Instances: A list of instance resources, if query parameter state is set return all instances with that state
  - `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` Instance[]
    - `alerts` Alert[]: A list of alerts against an instance
      - `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.
    - `id` string: A unique id for an instance
    - `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."
    - `dimensions` Codelist[]: A list of codelists for each dimension of this instance
      - `href` string: A link to the codelist corresponding to this dimension
      - `id` string: The codelist id corresponding to this dimension
      - `name` string: The dimension name
      - `description` string: The dimension description
      - `label` string: A human readable label for dimension
    - `downloads` object: 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
      - `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.
    - `events` Event[]: A list of events took place for this job
      - `message` string: A description of the event
      - `message_offset` string: The kafka message offset (Used to locate the kafka message)
      - `time` string: The time of the event in ISO 8601 format
      - `type` string: The type of event, this can be; * Info - for an information event * Error - for an error event
    - `headers` string[]: The header information from a V4 file
    - `import_tasks` ImportTasks
      - `build_hierarchies` object[]
        - `code_list_id` string: The ID of the codelist that this hierarchy represents
        - `dimension_name` string: The name of the dimension the hierarchy represents
        - `state` string: The state of the import observations task
      - `build_search_indexes` object[]
        - `dimension_name` string: The name of the dimension the search index represents
        - `state` string: The state of the import observations task
      - `import_observations` object
        - `state` string: The state of the import observations task
        - `total_inserted_observations` integer: The number of inserted observations in this instance
    - `last_updated` string: The last time an event happened
    - `links` object
      - `dataset` object: An object describing the ID and URL for a dataset which is associated with this instance
        - `href` string: The URL for the dataset associated with this instance
        - `id` string: The unique identifier for a dataset. The dataset ID cannot be changed once the series is first published.
      - `dimensions` object: An object describing the URL for the dimensions which are associated with this instance
        - `href` string: The URL for a list of dimensions associated with this instance
      - `edition` object: An object describing the ID and URL for the dataset edition that is associated with this instance
        - `href` string: The URL for the dataset edition associated with this instance
        - `id` 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.
      - `job` object: An object describing the ID and URL of the job containing this instance
        - `href` string, required: The URL for the job containing this instance
        - `id` string, required: The ID of the job containing this instance
      - `self` object: An object describing the ID and URL for a dataset which is associated with this instance
        - `href` string: The URL for this resource
      - `version` object: An object describing the ID and URL of the dataset version associated with this instance
        - `href` string: The URL for the dataset version associated with this instance
        - `id` string: The ID of the dataset version associated with this instance
    - `release_date` string, date-time: 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
    - `total_observations` integer: The number of observations in this instance
    - `version` integer: The dataset version number that this instance is associated with, this will only be set once the state has been updated to `edition-confirmed`

## Other responses

- `400`: Failed to process the request due to invalid request
- `401`: The token provided is unauthorised to carry out this operation
- `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)