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

# Get images filtered by collection id

`GET /images`

## Request

- Base URL: `/v1` (relative, and the document’s source URL is not known)
- URL: `/v1/images`
- Auth: one of:
  - API key in header `X-Florence-Token`
  - API key in header `Authorization`

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.dev/office-of-national-statistics/apis/image-api.md) - [All operations](https://skmtc.dev/office-of-national-statistics/apis/image-api/llms.txt) - [OpenAPI document](https://skmtc.dev/office-of-national-statistics/apis/image-api/revisions/0d1060eb31c2?raw)