---
title: "Find similar images"
method: GET
path: "/api/images/{imageId}/similar"
tags: ["Images"]
---

# Find similar images

`GET /api/images/{imageId}/similar`

## Request

- Base URL: `https://platform.ultralytics.com`
- URL: `https://platform.ultralytics.com/api/images/{imageId}/similar`
- Auth: HTTP bearer

Returns visually similar images from public datasets and your own and team datasets, with their similarity score, source dataset, and license, automatically embedding the query image when needed. By default, excludes the source dataset and datasets containing copies of the query image. Set includeSourceDataset=true to include those datasets. Copies of the query image remain excluded.

## Path parameters

- `imageId` string, required

## Query parameters

- `includeSourceDataset` 'true' | 'false'

## Response `200`

Similar images with filenames and dimensions

- SimilarImagesResponse
  - `images` object[], required
    - `name` string, required
    - `hash` string, required
    - `width` integer, required
    - `height` integer, required
    - `id` string, required
    - `thumbnailUrl` string, uri, required
    - `imageUrl` string, uri
    - `dataset` object, required
      - `owner` string, required
      - `dataset` string, required
      - `license` 'None' | 'CC0-1.0' | 'PDM-1.0' | 'CC-BY-2.5' | 'CC-BY-3.0' | 'CC-BY-4.0' | 'CC-BY-NC-2.0' | 'CC-BY-NC-3.0' | 'CC-BY-NC-4.0' | 'CC-BY-SA-3.0' | 'CC-BY-SA-4.0' | 'CC-BY-NC-SA-3.0' | 'CC-BY-NC-SA-4.0' | 'CC-BY-ND-4.0' | 'CC-BY-NC-ND-2.0' | 'CC-BY-NC-ND-4.0' | 'Apache-2.0' | 'MIT' | 'BSD-3-Clause' | 'AGPL-3.0' | 'GPL-2.0' | 'GPL-3.0' | 'LGPL-3.0' | 'ODbL-1.0' | 'DbCL-1.0' | 'Research-Only' | 'Other', required: Dataset license identifier
    - `score` number, required: Cosine similarity rescaled to 0-1 as (1 + cos) / 2

## Other responses

- `400`: Invalid image ID or query parameters
- `401`: Missing or invalid authentication
- `404`: Image not found
- `409`: AI features are off or unavailable for this image's storage
- `429`: Rate limit exceeded
- `503`: Image embedding could not be prepared; retry the search

## Changes

- **2026-10-23** `1b09776f4a4b`: 1 info
  - added the non-success response with the status `409`
- **2026-10-16** `709f6448e6ea`: 1 info
  - added the new optional `query` request parameter `includeSourceDataset`
- **2026-09-23** `c065e2b9d343`: 1 info
  - added the non-success response with the status `503`
- **2026-09-17** `51981d882390`: 4 info
  - added the required property `images/items/hash` to the response with the `200` status
  - added the required property `images/items/height` to the response with the `200` status
  - added the required property `images/items/name` to the response with the `200` status
  - added the required property `images/items/width` to the response with the `200` status
- **2026-09-03** `1279bde3d7c9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ultralytics/apis/ultralytics-platform-api/changes/api/images/:imageId/similar/get.md)

---

[API](https://skmtc.dev/ultralytics/apis/ultralytics-platform-api.md) - [All operations](https://skmtc.dev/ultralytics/apis/ultralytics-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ultralytics/apis/ultralytics-platform-api/revisions/9c562e23b0e4?raw)