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

# Semantic Search

> Run direct vector search over semantic indexes.

## Endpoints

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

Use semantic search when you know which semantic index or indexes to search directly.

## Request body

| Field             |             Type | Required | Description                                                 |
| ----------------- | ---------------: | -------: | ----------------------------------------------------------- |
| `query`           |           string |      yes | Text to search for.                                         |
| `index_names`     |      string/list |       no | Semantic index names to search.                             |
| `index_ids`       |      string/list |       no | Semantic index IDs to search.                               |
| `top_k`           |          integer |       no | Maximum returned moments. Defaults to `10`.                 |
| `score_threshold` |           number |       no | Minimum similarity score.                                   |
| `filter`          |      list/object |       no | Structured filter over supported fields/vector metadata.    |
| `return_fields`   | string/list/dict |       no | Select indexes to hydrate under `shot.metadata["indexes"]`. |

If `index_names` and `index_ids` are omitted, VideoDB searches all semantic indexes in scope.

<Note>
  The Python SDK argument is `index_names`, not singular `index_name`. Use `index_ids` for ID selection.
</Note>

## Example

```python theme={null}
results = video.semantic_search(
    query="happy reunion outside a shop",
    index_names=["scene"],
    top_k=10,
    score_threshold=0.7,
    return_fields=["scene"],
)

for shot in results:
    print(shot.start, shot.end, shot.search_score)
```

## Example with index IDs

```python theme={null}
results = collection.semantic_search(
    query="person presenting at a podium",
    index_ids=["idx_scene_123"],
    top_k=20,
)
```

## Response

Returns a `SearchResult` containing `Shot` objects. `SearchResult.compile()` can compile all returned shots into one stream.