---
title: "Get images filtered by collection id"
method: GET
path: "/images"
tags: ["image"]
---

# Get images filtered by collection id

`GET /images`

Returns a list of images metadata filtered by an optional query parameter defining the collection ID

## Query parameters

- `collection_id` string

## Response `200`

A json object containing a list of images

- Images — A list of images
  - `count` integer — The number of images returned
  - `items` Image[]
    - `id` string, required — Image metadata unique identifier
    - `collection_id` string, required — Collection unique identifier corresponding to this image
    - `state` 'created' | 'uploaded' | 'importing' | 'imported' | 'published' | 'completed' | 'deleted' | 'failed_import' | 'failed_publish', required — The state of the image
    - `error` string — Any error information, if there was an error with this image
    - `filename` string — Image's file name. According to SEO recommendations, the name should not be longer than 5 words. And it should not include extension because multiple extensions for the same image might be available as download variants.
    - `license` object — License that defines the third party permissions for this image
      - `title` string — Title of the license
      - `href` string — Link to the license content
    - `links` ImageLinks
      - `self` string
      - `downloads` string
    - `upload` ImageUpload — Original file upload in the upload bucket
      - `path` string — S3 object key (without bucket name) where the originally uploaded image is stored
    - `type` string, required — Type of image, which might define a set of possible formats and variants or resolutions.
  - `limit` integer — The number of images requested
  - `offset` integer — The first row of images to retrieve, starting at 0. Use this parameter as a pagination mechanism along with the limit parameter
  - `total_count` integer — The total number of images

## Other responses

- `400` — Invalid request
- `401` — User or service is not authenticated
- `403` — Unauthorised to view images metadata
- `500` — Failed to process the request due to an internal error

---

[API](https://skmtc.net/office-of-national-statistics/apis/image-api.md) · [All operations](https://skmtc.net/office-of-national-statistics/apis/image-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/office-of-national-statistics/image-api/revisions/0d1060eb31c2/schema)