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

# Semantic Search

> Search your dataset using natural language captions or AI-powered semantic similarity—powered by enrichment models.

<Card title="How This Helps" icon="hand-platter">
  Semantic Search lets you find images using plain language. A query like "car on highway at night" returns visually and contextually relevant results—even if none of the images are explicitly labeled that way.
</Card>

## Prerequisites

* A dataset ID (visible in the browser URL when viewing a dataset: `https://app.visual-layer.com/dataset/<dataset_id>/data`).
* A valid JWT token. See [Authentication](/api-reference/authentication).

Semantic search requires enrichment to have been applied to your dataset.

* **Caption search** (`caption` parameter): requires **CAPTION\_IMAGES** enrichment.
* **Semantic vector search** (VQL `text` filter): requires **MULTIMODEL\_IMAGE\_ENCODING** or **CAPTION\_IMAGES** enrichment.
* **Full-text search** (VQL `fts`): works on any dataset with captions.

<Note>
  Check which enrichment models are applied to your dataset by calling `GET /api/v1/enrichment/{dataset_id}/context`.
</Note>

***

## Caption Search

The `caption` query parameter searches across AI-generated captions using semantic similarity.

```http theme={"theme":"monokai"}
GET /api/v1/explore/{dataset_id}
Authorization: Bearer <jwt>
```

### Parameters

| Parameter                      | Type    | Required | Description                                                                                                                     |
| ------------------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `caption`                      | string  | Yes      | Natural language search query.                                                                                                  |
| `entity_type`                  | string  | Yes      | `IMAGES` or `OBJECTS`.                                                                                                          |
| `threshold`                    | integer | No       | Clustering granularity (0–4). Use `0` for finest granularity.                                                                   |
| `textual_similarity_threshold` | float   | No       | Minimum similarity score to include in results (0.0–1.0).                                                                       |
| `page_number`                  | integer | No       | Page index for pagination (0-based, 100 clusters per page).                                                                     |
| `labels`                       | string  | No       | Filter by label. Format: `["label1","label2"]`. Labels are generated by the **IMAGE\_TAGGING** enrichment model.                |
| `tags`                         | string  | No       | Filter by tag UUID. Format: `["uuid1","uuid2"]`. Tag UUIDs are returned in search responses and visible in the Visual Layer UI. |

### Example

```bash theme={"theme":"monokai"}
curl -H "Authorization: Bearer <jwt>" \
  "https://app.visual-layer.com/api/v1/explore/<dataset_id>?caption=cars+on+highway&entity_type=IMAGES&threshold=0&textual_similarity_threshold=0.5"
```

### Response

```json theme={"theme":"monokai"}
{
  "clusters": [
    {
      "cluster_id": "d0470097-0c77-4a9c-9edf-289680df7f71",
      "type": "IMAGES",
      "n_images": 14,
      "similarity_threshold": "0",
      "relevance_score": 0.63,
      "relevance_score_type": "cosine_distance",
      "captions": [
        "An aerial view of a highway with multiple vehicles traveling at night."
      ],
      "previews": [
        {
          "type": "IMAGE",
          "media_id": "300dad2c-1234-11f1-8483-5a879df30de4",
          "media_uri": "https://cdn.example.com/.../image.jpg",
          "media_thumb_uri": "https://cdn.example.com/.../thumb.webp",
          "caption": "An aerial view of a highway with multiple vehicles traveling at night.",
          "file_name": "highway_night.jpg",
          "relevance_score": 0.63,
          "relevance_score_type": "cosine_distance",
          "width": 1920,
          "height": 1080
        }
      ],
      "labels": null,
      "user_tags": null
    }
  ],
  "metadata": {
    "used_duckdb": true
  }
}
```

### Understanding `relevance_score`

When `relevance_score_type` is `cosine_distance`, a **lower score means a stronger match**.

* `0.0–0.4` — strong match
* `0.4–0.6` — partial match
* `0.6+` — loosely related

Use `textual_similarity_threshold` to filter out weak matches. A value of `0.5` returns only results with a score below 0.5 (higher similarity).

<Note>
  The `image_caption` parameter is deprecated. Use `caption` instead.
</Note>

***

## VQL Text Search

Visual Query Language (VQL) is the preferred approach for advanced text queries. It supports both full-text search and semantic vector search, and it composes cleanly with other filters.

Pass VQL as a JSON array in the `vql` query parameter.

```http theme={"theme":"monokai"}
GET /api/v1/explore/{dataset_id}?vql=[...]&entity_type=IMAGES&threshold=0
Authorization: Bearer <jwt>
```

### Full-Text Search

Full-text search (`fts`) matches captions using stemming and keyword ranking.

```bash theme={"theme":"monokai"}
curl -H "Authorization: Bearer <jwt>" \
  "https://app.visual-layer.com/api/v1/explore/<dataset_id>?vql=%5B%7B%22text%22%3A%7B%22op%22%3A%22fts%22%2C%22value%22%3A%22highway+night%22%7D%7D%5D&entity_type=IMAGES&threshold=0"
```

Decoded VQL:

```json theme={"theme":"monokai"}
[{"text": {"op": "fts", "value": "highway night"}}]
```

### Semantic Search

Semantic search (`semantic`) uses vector embeddings to find conceptually similar content — even when the exact words don't appear in the captions.

```bash theme={"theme":"monokai"}
curl -H "Authorization: Bearer <jwt>" \
  "https://app.visual-layer.com/api/v1/explore/<dataset_id>?vql=%5B%7B%22text%22%3A%7B%22op%22%3A%22semantic%22%2C%22value%22%3A%22cars+on+highway%22%2C%22threshold%22%3A0.7%7D%7D%5D&entity_type=IMAGES&threshold=0"
```

Decoded VQL:

```json theme={"theme":"monokai"}
[{"text": {"op": "semantic", "value": "cars on highway", "threshold": 0.7}}]
```

The optional `threshold` in the VQL filter (0.0–1.0) sets the minimum similarity score for results.

***

## Combining Filters with VQL

VQL filters combine with AND logic. The following example finds semantically similar images that are also labeled as vehicles.

```json theme={"theme":"monokai"}
[
  {"text": {"op": "semantic", "value": "car on highway"}},
  {"labels": {"op": "one_of", "value": ["vehicle", "car"]}}
]
```

```bash theme={"theme":"monokai"}
curl -H "Authorization: Bearer <jwt>" \
  "https://app.visual-layer.com/api/v1/explore/<dataset_id>?vql=%5B%7B%22text%22%3A%7B%22op%22%3A%22semantic%22%2C%22value%22%3A%22car+on+highway%22%7D%7D%2C%7B%22labels%22%3A%7B%22op%22%3A%22one_of%22%2C%22value%22%3A%5B%22vehicle%22%2C%22car%22%5D%7D%7D%5D&entity_type=IMAGES&threshold=0"
```

### Available VQL Filter Types

| Filter       | Description                              | Example                                                      |
| ------------ | ---------------------------------------- | ------------------------------------------------------------ |
| `text`       | Search by caption text (fts or semantic) | `{"text": {"op": "semantic", "value": "dog"}}`               |
| `labels`     | Filter by classification labels          | `{"labels": {"op": "one_of", "value": ["cat"]}}`             |
| `tags`       | Filter by user tag UUIDs                 | `{"tags": {"op": "is", "value": ["uuid"]}}`                  |
| `issues`     | Filter by quality issues                 | `{"issues": {"op": "issue", "value": "blur", "mode": "in"}}` |
| `duplicates` | Show duplicate clusters                  | `{"duplicates": {"op": "duplicates", "value": 0.95}}`        |
| `uniqueness` | Filter by uniqueness score               | `{"uniqueness": {"op": "uniqueness", "value": 0.8}}`         |

***

## Python Example

```python theme={"theme":"monokai"}
import requests
from urllib.parse import quote
import json

VL_BASE_URL = "https://app.visual-layer.com"
JWT_TOKEN = "<your-jwt-token>"
DATASET_ID = "<your-dataset-id>"

headers = {"Authorization": f"Bearer {JWT_TOKEN}"}

def semantic_search(query: str, threshold: float = 0.6, page: int = 0):
    vql = json.dumps([{"text": {"op": "semantic", "value": query, "threshold": threshold}}])
    resp = requests.get(
        f"{VL_BASE_URL}/api/v1/explore/{DATASET_ID}",
        headers=headers,
        params={
            "vql": vql,
            "entity_type": "IMAGES",
            "threshold": 0,
            "page_number": page,
        },
    )
    resp.raise_for_status()
    return resp.json()

results = semantic_search("cars driving on a highway at night")
clusters = results.get("clusters", [])
print(f"Found {len(clusters)} clusters")

for cluster in clusters:
    score = cluster.get("relevance_score")
    n = cluster.get("n_images")
    captions = cluster.get("captions", [])
    caption_preview = captions[0][:80] if captions else "no caption"
    print(f"  {n} images — score: {score:.3f} — {caption_preview}...")
```

***

## Response Codes

See [Error Handling](/api-reference/errors) for the error response format and Python handling patterns.

| HTTP Code | Meaning                                      |
| --------- | -------------------------------------------- |
| **200**   | Results returned successfully.               |
| **401**   | Unauthorized — check your JWT token.         |
| **404**   | Dataset not found.                           |
| **422**   | Invalid query parameters — check VQL syntax. |

***

## Related Resources

<CardGroup cols={2}>
  <Card title="Visual Search" icon="scan-search" href="/api-reference/visual-search">
    Search using a query image instead of text.
  </Card>

  <Card title="Enrichment" icon="sparkles" href="/docs/advanced-dataset-management/enrich-overview">
    Apply AI models to enable semantic search.
  </Card>
</CardGroup>