> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videodb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# High-level Search & DeepSearch

> Run Search V2 natural-language retrieval on a video or collection.

## Endpoints

```http theme={null}
POST /video/{video_id}/search/v2/
POST /collection/{collection_id}/search/v2/
```

Use high-level `search()` when VideoDB should plan retrieval across available indexes. Use `mode="deepsearch"` for deeper multi-step retrieval with optional follow-up sessions.

## Request body

| Field                  |               Type | Required | Description                                                                                              |
| ---------------------- | -----------------: | -------: | -------------------------------------------------------------------------------------------------------- |
| `query`                |             string |      yes | Natural-language search request.                                                                         |
| `top_k`                |            integer |       no | Maximum returned moments. Defaults to `10`.                                                              |
| `mode`                 |             string |       no | `"default"` or `"deepsearch"`. Defaults to `"default"`.                                                  |
| `filter`               |        list/object |       no | Default-mode structured filter applied where supported by selected indexes. Not supported in DeepSearch. |
| `sort`                 | list/string/object |       no | Default-mode sort applied where supported. Not supported in DeepSearch.                                  |
| `score_threshold`      |             number |       no | Default-mode semantic score threshold where applicable. Not supported in DeepSearch.                     |
| `return_fields`        |   string/list/dict |       no | Select indexes to hydrate under `shot.metadata["indexes"]`. Use `"all"` to hydrate all.                  |
| `session_id`           |             string |       no | DeepSearch follow-up session ID. Only valid with `mode="deepsearch"`.                                    |
| `config.include_trace` |            boolean |       no | Include planner trace for default-mode search.                                                           |

<Note>
  High-level Search V2 does not accept `index_name`, `index_names`, `index_id`, or `index_ids`. Use semantic search, query, or aggregate for index-specific calls.
</Note>

## Example: default search

```python theme={null}
response = collection.search(
    query="person talking about Nike while holding a phone",
    top_k=10,
    mode="default",
    return_fields=["scene", "transcript", "brands"],
)

for shot in response:
    print(shot.video_id, shot.start, shot.end)
```

## Example: DeepSearch

```python theme={null}
response = collection.search(
    query="find the strongest examples of customers reacting negatively to pricing",
    mode="deepsearch",
    top_k=10,
    return_fields="all",
)

followup = collection.search(
    query="only include competitor mentions",
    mode="deepsearch",
    session_id=response.session_id,
    top_k=10,
)
```

## Response

`search()` returns a `SearchResponse`.

| Attribute       | Description                                                                              |
| --------------- | ---------------------------------------------------------------------------------------- |
| `response_type` | `"shots"`, `"aggregate"`, or `"deepsearch"`.                                             |
| `results`       | `SearchResult` for shot/deepsearch responses, or aggregate rows for aggregate responses. |
| `shots`         | Convenience list of `Shot` objects for shot/deepsearch responses.                        |
| `session_id`    | DeepSearch session ID, when applicable.                                                  |
| `waiting_for`   | DeepSearch waiting state, when applicable.                                               |
| `clarification` | DeepSearch clarification, when applicable.                                               |
| `trace`         | Planner trace when requested with `config={"include_trace": True}`.                      |