---
title: "Look up photos in the user registry"
method: POST
path: "/v2/lookup"
tags: ["Registry"]
---

# Look up photos in the user registry

`POST /v2/lookup`

## Request

- Base URL: `https://api.phototology.com`
- URL: `https://api.phototology.com/v2/lookup`
- Auth: HTTP bearer

Submit one or more images (URL or base64) and receive the full `PhotoRecord` for each. The record is the registry projection keyed by lens. Free endpoint, no credits charged.

### When to use
Call this before `POST /v2/analyze` whenever you have image inputs. Any photo already in the registry (by exact SHA-256 or perceptual hash) comes back here for free, so you only spend credits on genuine cache misses. This is the registry-first path that makes repeat work cost zero.

### Match tiers
- **exact**: SHA-256 equality
- **fuzzy**: pHash Hamming distance within `threshold` (default 5, max 64)
- **none**: no registry entry; `photo` is omitted

### Response shape
The `results` object is keyed by SHA-256. Each `PhotoRecord.lenses` is a map from lens name to the latest lens output (`output`, `version`, `producedAt`, `coRunHash`, `provider`).

## Request body

- object
  - `images` string[]
  - `images_base64` string[]
  - `threshold` integer

## Response `200`

Lookup complete. Each result carries the full `PhotoRecord` on exact/fuzzy matches.

- object
  - `object` 'lookup', required
  - `results` object, required
  - `meta` object, required
    - `imagesSubmitted` integer, required
    - `imagesMatched` integer, required
    - `processingTimeMs` integer, required
    - `requestId` string, required

## Other responses

- `400`: Validation failed (missing images, bad URL, SSRF-blocked host).
- `401`: Missing or invalid API key.
- `429`: Lookup rate limit exceeded (300 req/min per key).

---

[API](https://skmtc.dev/phototology/apis/phototology-api.md) · [All operations](https://skmtc.dev/phototology/apis/phototology-api/llms.txt) · [OpenAPI document](https://skmtc.dev/phototology/apis/phototology-api/revisions/3cb0fc707b63?raw)