> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/datasets/manage/manage-datasets/dataset-search.md).

# Search a Dataset

Use text-based search queries and set filters to better understand datasets in Roboflow.

## About

Dataset search lets you find specific images across a project using file-name lookups, structured filters (tags, splits, classes, dimensions, annotation counts), boolean logic, and natural-language semantic search. Use it to audit your data, surface mislabeled or missing annotations, and build targeted subsets for review or export. The same queries are available in the web app and through the search REST API.

## Web App

You can search for image files in Roboflow by file name, a search query, and mix and match queries and filters to find specific images and better understand your data.

* **Images in a split with a certain tag:**\
  `tag:factory split:train`\
  This uses a tag filter and a split filter
* **Find missing labels by using semantic search and a class filter**:\
  `person -class:helmet`\
  This uses semantic search and an inverted filter on a class filter
* **If all images with a class need a certain filter:**\
  `class:helmet AND NOT (tag:v1 OR tag:v2)`\
  This uses a class filter, boolean logic, and tag filters
* **Find wide images with a low number of annotations:**\
  `min-width:1000 max-annotations:1`\
  This uses a minimum width filter and a max annotation count filter

See the full list of [search filters](#search-filters), as well as examples below

{% hint style="info" %}
You can combine all of these search filters and queries together
{% endhint %}

### Semantic Search

You can search for images by describing them. These queries will search for images most closely related to your search terms and can help you find images even when objects are not currently labeled.

Semantic search happens when you enter a text query without any filter selectors (ex: `filename:`)

<figure><img src="https://2252499186-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-252e7735b8f04fdeb7b567c8a73c783ba42c7ba0%2Fimage%20(355).png?alt=media" alt=""><figcaption></figcaption></figure>

### Search by File Name

You can search for file names using the `filename:` filter or the file name textbox, which will create the query for you.

<figure><img src="https://2252499186-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-007ef7663b94243be3a88de95df3a6fe6345bf5f%2Fimage%20(354).png?alt=media" alt="" width="192"><figcaption></figcaption></figure>

### Search by Dataset Split

Search images by the dataset split (train, valid, test)

<figure><img src="https://2252499186-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-42804a6e68a1551a7f23c0fe1746da8231fb5b02%2Fimage%20(356).png?alt=media" alt="" width="257"><figcaption></figcaption></figure>

To reassign images to a different split, select them (or choose "Select all matching" from a search) and click "Change Dataset Split" in the bulk actions menu. Large selections process in the background.

### Search by Upload Date

Filter images by the date they were first uploaded to Roboflow using the `date:` filter. The upload date is immutable and does not change when an image is edited, re-annotated, or moved between splits.

Use `date:YYYY-MM-DD` for an exact day, or combine comparison operators to search a range:

`date>=2026-01-01 date<2026-02-01`

### Search Filters

Here are the filters available:

* `like-image:<IMAGE_ID>`: Semantic search based on image content
* `tag` : Filter by user-provided tags.
* `filename` : Runs a search for file names that match the provided file name. Use \* at the beginning and end of a query to run a partial match.
* `split` : Filters by split (train, test, valid).
* `job:<JOB_ID>` : Shows images with the provided job ID.
* `min-width:X` : Shows images with a width of at least X pixels.
* `max-width:X` : Shows images with a width of at most X pixels.
* `min-height:X` : Shows images with a height of at least X pixels.
* `max-height:X` : Shows images with a height of at most X pixels.
* `min-annotations:X` : Shows images with at least X annotations.
* `max-annotations:X` : Shows images with at most X annotations. Use `max-annotations:0` to find images without annotations.
* `class:CLASS`: Shows images that have at least 1 annotation with the provided label.
* `date:YYYY-MM-DD` : Filters by the immutable date an image was uploaded. Supports comparison operators (ex: `date>=2026-01-01 date<2026-02-01`).

#### Boolean Logic

Use AND, OR, NOT, and parentheses to combine multiple filters to form complex queries.

`class:helmet AND NOT (tag:v1 OR tag:v2)`

#### Inverted Filters

Add a minus sign before the filter to exclude images matching the filter.

`class:helmet -class:vest`

#### Numeric Class Filters

Filter by the number of labeled items in an image.

`class:helmet=3 class:vest>=4`

### API

You can also search your dataset and images on Roboflow via the [Search API](#http-api).

## HTTP API

There are two search endpoints: one searches a single project, and one searches the whole workspace with the same query syntax as the [web app dataset search](#web-app).

### Search Images in a Project

Filter a project's images by tag, class, batch, annotation job, or Dataset membership. Add `prompt` to sort results by a text description, or `like_image` to sort by similarity to another image. Page through results with `offset` and `limit`.

{% openapi src="/files/OrInDMlwV1Kfuzb0nC0i" path="/{workspace}/{project}/search" method="post" %}
[dataset-search.yaml](https://2252499186-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-3bf42847152663cfead69cbf3ebf988912a834a4%2Fdataset-search.yaml?alt=media)
{% endopenapi %}

### Search Images Across a Workspace

Send a RoboQL `query` with any of the [search filters](#search-filters). Free text in the query runs a semantic search. Two more filters work here: `project:foo` returns images in project `foo`, and `dataset:foo` returns images in the Dataset of project `foo`. Repeat a filter to require both (ex: `project:foo project:bar`). An empty query returns every image in the workspace.

To get the next page, send the `continuationToken` from the response with the same query.

{% openapi src="/files/OrInDMlwV1Kfuzb0nC0i" path="/{workspace}/search/v1" method="post" %}
[dataset-search.yaml](https://2252499186-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-3bf42847152663cfead69cbf3ebf988912a834a4%2Fdataset-search.yaml?alt=media)
{% endopenapi %}

## Python SDK

`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.

```python
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) - whether to restrict results to images in the project's dataset, excluding 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()`. Unlike the per-project methods, these take a single RoboQL `query` string (for example `"class:forklift"`, `"tag:review"`, or free text for semantic CLIP search) plus optional `page_size` and `fields`. Each yielded page is a list of result rows, and the rows include the source project under a `projects` field.

```python
records = []
for page in rf.workspace().search_all(query="class: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.). It calls the [search export endpoints](https://docs.roboflow.com/reference/platform/rest-api/platform-api-openapi#search) of the Platform API.

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

## CLI

You can search images across your workspace using [RoboQL](/datasets/manage/manage-datasets/dataset-search.md) and optionally export matching results as a downloadable dataset.

### Search

```bash
roboflow search "<query>"
```

#### Options

| Flag       | Description                               |
| ---------- | ----------------------------------------- |
| `--limit`  | Max results to return (default: 50)       |
| `--cursor` | Continuation token for pagination         |
| `--fields` | Comma-separated list of fields to include |

#### Examples

Search for images with a specific tag:

```bash
roboflow search "tag:reviewed"
```

Search for images containing a specific class:

```bash
roboflow search "class:person" --limit 100
```

### Export Search Results

Add `--export` to download matching images as a dataset:

```bash
roboflow search "<query>" --export -f <format> -l <location>
```

#### Export Options

| Flag                       | Description                          |
| -------------------------- | ------------------------------------ |
| `--export`                 | Enable export mode                   |
| `-f`, `--format`           | Annotation format (default: coco)    |
| `-l`, `--location`         | Local directory to save the export   |
| `-d`, `--dataset`          | Limit to a specific project          |
| `-g`, `--annotation-group` | Limit to a specific annotation group |
| `--name`                   | Optional name for the export         |
| `--no-extract`             | Keep zip file, skip extraction       |

#### Examples

Export all reviewed images in COCO format:

```bash
roboflow search "tag:reviewed" --export -f coco -l ./reviewed-export
```

Export images from a specific project in YOLOv8 format:

```bash
roboflow search "class:car" --export -d my-project -f yolov8 -l ./cars
```

### JSON Output

```bash
roboflow search "tag:reviewed" --json
```

```json
{
  "results": [...],
  "total": 42,
  "cursor": "next-page-token"
}
```

Use the `cursor` value for pagination:

```bash
roboflow search "tag:reviewed" --cursor "next-page-token" --json
```

## MCP Server

Connect your AI agent to the [MCP Server](https://docs.roboflow.com/agents/mcp-server) and it can find images with these tools:

<table data-search="false"><thead><tr><th width="290">Tool</th><th>Description</th></tr></thead><tbody><tr><td><code>images_search</code></td><td>Search for images inside a project.</td></tr><tr><td><code>images_workspace_search</code></td><td>Search images across the entire workspace using RoboQL.</td></tr></tbody></table>