Search

Find images by visual similarity to a reference image, or by automatic content tags (objects / scenes / attributes).

Two search modes, both indexed automatically on upload - no setup, no extra cost:

Visual similarity - nearest neighbours of a reference image in learned embedding space.
Tag-based - exact match against the content tags generated for every image (objects / scenes / attributes).

by_similarity

Find images visually similar to a reference image. Scope is the reference image’s dataset and directory unless overridden.

Source: Search.by_similarity

Arg	Type	Default	Notes
`dataset_name`	`str`	required	Dataset name.
`image`	`str`	required	Reference image’s filename (an id also works)
`threshold`	`float`	`0.6`	Minimum cosine similarity; `0.6` is roughly “visually related”
`limit`	`int`	`50`	Backend cap: 500
`directory_path`	`str \| None`	`None`	Override the directory scope; `"/"` is the dataset root

results = client.search.by_similarity(
    dataset_name="road-signs",
    image="stop-sign-0421.jpg",
    threshold=0.6,
    limit=50,
)
for r in results:
    print(r.id, r.filename, f"{r.similarity:.3f}")

pictograph search similar road-signs stop-sign-0421.jpg --threshold 0.6 -n 50

curl -s "https://api.pictograph.io/api/v1/developer/search/similar?image_id=a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d&threshold=0.6&limit=50" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns list[SimilarImage]

SimilarImage · 7 fields

class SimilarImage(BaseModel):
    """One result from pictograph.resources.search.Search.by_similarity."""
    id: str
    filename: str
    virtual_directory_path: str = '/'
    status: Literal['new', 'annotate', 'review', 'complete']
    annotation_count: int
    image_auto_tags: dict[str, Any] = {}
    similarity: float

The SDK and CLI take (dataset_name, image filename) and resolve the reference image for you. The REST endpoint takes the resolved image_id UUID directly - read one from GET /api/v1/developer/images/?dataset=road-signs.

by_tag

Find images whose content tags match the given filters. At least one of objects / scenes / attributes is required - an empty filter is rejected rather than returning everything.

Source: Search.by_tag

Arg	Type	Default	Notes
`objects`	`Sequence[str] \| None`	`None`	At least one of the three categories is required
`scenes`	`Sequence[str] \| None`	`None`	Scene tags to match, e.g. `highway`. Combined with the other tag arguments.
`attributes`	`Sequence[str] \| None`	`None`	Attribute tags to match, e.g. `night`. Combined with the other tag arguments.
`dataset_name`	`str \| None`	`None`	Whole organization when `None`
`limit`	`int`	`50`	Backend cap: 500
`offset`	`int`	`0`	Pagination offset

results = client.search.by_tag(
    objects=["car", "truck"],
    scenes=["outdoor"],
    attributes=["blurry"],
    dataset_name="my-dataset",
    limit=100,
)
for r in results:
    print(r.id, r.image_auto_tags["objects"])

pictograph search tags \
  --object car --object truck \
  --scene outdoor \
  --attribute blurry \
  --dataset my-dataset -n 100

curl -s "https://api.pictograph.io/api/v1/developer/search/by-tags?objects=car&objects=truck&scenes=outdoor&attributes=blurry&dataset_name=my-dataset&limit=100" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns list[TaggedImage]

TaggedImage · 7 fields

class TaggedImage(BaseModel):
    """One result from pictograph.resources.search.Search.by_tag."""
    id: str
    dataset_id: str
    filename: str
    virtual_directory_path: str = '/'
    status: Literal['new', 'annotate', 'review', 'complete']
    annotation_count: int
    image_auto_tags: dict[str, Any] = {}

Tags match exactly and are AND’d both within and across categories - every listed tag must be present:

objects=["car", "truck"] means “car AND truck”
objects=["car"], scenes=["outdoor"] means “car AND outdoor”

Repeat the key per value in REST (objects=car&objects=truck) and repeat the flag per value in the CLI (--object car --object truck).

Auto-tag taxonomy

The classifier picks from a fixed set of roughly 200 curated labels per category. Tags outside the list are never assigned.

objects: car, truck, person, bicycle, dog, sign, building, and similar
scenes: outdoor, indoor, urban, rural, daytime, nighttime, and similar
attributes: blurry, dark, bright, high-contrast, low-light, and similar

Cost

Search is free. Embeddings and auto-tags are computed once per image on upload and cached.

Common errors

Status	Exception	Cause
404	`NotFoundError`	Reference image or `dataset_name` not found in this organization
400	`ValidationError`	`by_tag` called with all three categories empty