# Search Images in a Dataset

The Workspace Image Search API lets you ilst and search images within your workspace.

With this API, you can filter, sort, and perform semantic searches using a query string that is similar to [the image search feature in the Roboflow web application](/developer/rest-api/manage-images/search-for-an-image.md).

### Endpoint

To make a request to the API, send a `POST` request to the following endpoint:

```
https://api.roboflow.com/{WORKSPACE}/search/v1?api_key=API_KEY
```

Where `WORKSPACE` is your Workspace ID, and `API_KEY` is your API key.

[Learn how to find your Workspace ID](/developer/authentication/workspace-and-project-ids.md).

[Learn how to find your API key.](/developer/rest-api/authenticate-with-the-rest-api.md)

### Authentication

To access the API, you need to include your API key in the request. The API key should be passed as a query parameter.

Example: `?api_key={YOUR_API_KEY}`

### Request Format

#### Headers

* `Content-Type: application/json`

#### Body Parameters

* `query` **(required)**: A non-empty string to filter, sort, or perform a semantic search. For example: `"nighttime project:{my-project-url}"` will filter for images in the `my-project-url` project and apply a semantic sort for images that match `nighttime`. Returns a 400 error if missing or empty.
* `pageSize`: Number of results to return per page (default: 50).
* `fields`: List of fields to include in the response. Possible values are `"tags"`, `"width"`, `"height"`, `"filename"`, `"aspectRatio"`, `"split"`, `"projects"`, `"annotations"`, `"labels"`.

#### Example Request

```bash
curl --location 'https://api.roboflow.com/{WORKSPACE}/search/v1?api_key={API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "query": "project:foo nightime",
    "pageSize": 10,
    "fields": ["tags", "width", "height", "filename", "aspectRatio", "split"]
}'

```

### Response Format

The response is a JSON object containing the following fields:

* `results`: An array of image objects.
* `total`: Total number of images found.
* `continuationToken`: A token for pagination.

#### Image Object Fields

depending on fields requested in the `fields` parameter:

* `id`: Unique identifier of the image.
* `projectData`: Object keyed by project URL, containing project-specific data:
  * `split`: Indicates the dataset split (e.g., "test"). Returned when `"split"` is in `fields`.
  * `inDataset`: Boolean indicating if the image is in the dataset. Returned when `"projects"` is in `fields`.
  * `annotations`: Annotation data for the image in this project, including `annotationGroup`, `classes`, and `classCounts`. Returned when `"annotations"` is in `fields`.
  * `labels`: Label data for the image in this project. Returned when `"labels"` is in `fields`.
* `tags`: Array of tags associated with the image.
* `width`: Width of the image in pixels.
* `height`: Height of the image in pixels.
* `filename`: Name of the image file.
* `aspectRatio`: Aspect ratio of the image.

#### Pagination and `continuationToken`

The `continuationToken` returned in the response lets you scroll between pages that match a search result. When the `continuationToken` is included in a subsequent request, it fetches the next set of results.

To use the `continuationToken`, include it in the request body of your next API call. This will retrieve the next page of results based on your original query.

#### Error Responses

* `400` - Returned when `query` is missing or empty, or when a `project:` filter references a project that does not belong to your workspace.
* `500` - Internal server error.

#### Project and Dataset Filters

In addition to all the filters available in [the in app dataset search](/developer/rest-api/manage-images/search-for-an-image.md), the workspace wide search also support filters for `project` and `dataset` . For example you can use a query like `project:foo project:bar` to find all images that are in both projects `foo` and `bar`.\
\
A query like `dataset:foo`will return images in project `foo` that have been labeled and are added to the dataset in the project.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.roboflow.com/developer/rest-api/search-images-in-a-dataset.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.