Search for an Image

Find images in your dataset by text prompt, similarity, tag, class name, or batch.

Project.search_all() returns a paginated iterator of search results across the images in a project. Search modes can be combined: a text prompt narrowed by class, an existing-image similarity search filtered to a single batch, etc.

import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
project = rf.workspace().project("my-detector")

records = []
for page in project.search_all(
    prompt="mug on a desk",
    class_name="mug",
    in_dataset=True,
    limit=100,
    fields=["id", "created", "name", "labels"],
):
    records.extend(page)

print(len(records))

Parameters

• prompt (str, optional) - natural-language search prompt (semantic search via CLIP embeddings).

• like_image (str, optional) - image id to search by visual similarity instead of text.

• tag (str, optional) - only images carrying this tag.

• class_name (str, optional) - only images that have an annotation in this class.

• in_dataset (bool, optional) - restrict to images currently in the dataset (excludes batch / annotation-job staging areas).

• batch (bool, optional) and batch_id (str, optional) - restrict to a specific upload batch.

• annotation_job (bool, kw-only) and annotation_job_id (str, kw-only) - restrict to a specific annotation job.

• offset (int, default 0) - pagination offset.

• limit (int, default 100) - page size.

• fields (list[str], optional) - request only the listed fields per result, to reduce response size.

search_all() is a generator - each iteration yields a page of up to limit results, automatically advancing the offset. For a one-shot single-page call, use project.search(...) with the same arguments.

Workspace-wide search

To search across every project in the workspace, use Workspace.search() / Workspace.search_all() with the same arguments. The result rows include the source project's id.

records = []
for page in rf.workspace().search_all(prompt="forklift"):
    records.extend(page)

Export search results as a downloadable dataset

Workspace.search_export() runs a search and packages the results as a downloadable dataset (COCO / YOLO / VOC etc.). See Export Data (REST) for the underlying endpoint.

path = rf.workspace().search_export(
    query="forklift",
    format="coco",
    location="./forklift-search",
)
print(path)

REST and CLI equivalents

• REST: see Search Images in a Dataset (REST) and Search for an Image (REST).

• CLI: see Search Images (CLI).