> This page is for version v1.3 (default).
> For other versions, use one of these documentation indexes:
> - v1.3 (default): https://beta.docs.twelvelabs.io/v1.3/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://beta.docs.twelvelabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://beta.docs.twelvelabs.io/_mcp/server.

# Search a knowledge store

POST https://api.twelvelabs.io/v1.3/knowledge-stores/{knowledge_store_id}/search
Content-Type: application/json

This method searches a knowledge store using natural language and returns matching video clips and images ranked by relevance.

Use the `query.text` field to specify your natural-language query. Use the `filter` parameter to choose which items to search. Use the `search_options` parameter to choose how the platform matches videos.

By default, each result is an individual match: a video clip or an image. Set the `group_by` parameter to `item` to group clips under their parent item.

This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page.

Reference: https://beta.docs.twelvelabs.io/api-reference/knowledge-store-search/search

## Authentication

- `x-api-key` header (required) — Your API key. You can find your API key on the API Keys page.

## Request

### Path parameters

- `knowledge_store_id` (string, required) — The unique identifier of the knowledge store.

### Body (application/json)

This endpoint expects a SearchKnowledgeStoreRequest.

- `query` (KnowledgeStoreSearchQuery, required) — The search query.
- `filter` (SearchKnowledgeStoreFilter, optional) — Narrows results to specific items in the knowledge store. Omit the filter to search all items. You can filter with these fields: * `asset_type`: The type of item. Use `eq` to match one type. Use `in` to match any type in a list. * `item_id`: Specific items. Use `eq` to match one item or `in` to match any item in a list. Use `nin` to exclude any item in a list. You cannot use `eq` and `in` together. You can use `nin` on its own or with either `eq` or `in`. If an item is listed in `nin` and selected by `eq` or `in`, the platform excludes it. * `item_collection_id`: Specific item collections. Use `eq` to match the items in one item collection. Use `in` with a list of item collections to match the items in any of them. If an item collection is not in the knowledge store, the platform returns a `404` error with the `resource_not_exists` code. If the identifier of an item collection is not valid, the platform returns a `400` error with the `parameter_invalid` code. * `user_metadata`: Custom metadata. Map each key to `eq`, `in`, or inclusive numeric or date bounds with `gte` and `lte`. * `enrichment`: Enrichment values that the platform extracts. Map each key to the `eq` operator to match one value, or to the `in` operator to match any value in a list. * `created_at`: Creation time. Use `gte` to set the earliest time and `lte` to set the latest time. You can use one or both. * `location`: Capture location. Provide the center and the radius of a circle. * `tags`: Item tags. Map each key under `tags.metadata` to the `eq` operator to match one value, or to the `in` operator to match any value in a list. An item must match all of the fields and metadata keys that you specify. The `tags` field also limits which clips of an item the search returns. When you use any of the `item_collection_id`, `user_metadata`, `enrichment`, `created_at`, or `location` fields, the platform counts the items that match those conditions together, including metadata ranges and the items that you include or exclude with the `item_id` field. If more than 10,000 items match, the platform returns a `422` error with the `metadata_filter_too_broad` code. To reduce the count, add conditions or use the `item_id` field. The `asset_type` field does not reduce the count. When you use the `tags` field, the platform does not count items, and this limit does not apply. It counts the matching tags instead, as the `tags` field describes. Examples: ```json { "asset_type": { "eq": "video" } } ``` ```json { "asset_type": { "in": [ "video" ] }, "item_id": { "in": [ "ksi_069e9870-3c4d-7abc-9012-3456789abcde" ] } } ``` ```json { "user_metadata": { "category": { "eq": "tutorial" } }, "created_at": { "gte": "2026-09-01T00:00:00Z" } } ``` ```json { "location": { "latitude": 37.5665, "longitude": 126.978, "radius_meters": 5000 } } ``` ```json { "tags": { "metadata": { "event": { "eq": "goal" } } } } ```
- `search_options` (SearchKnowledgeStoreOptions, optional) — Specifies how videos are matched. Videos are the only type of item with configurable options, set in the `search_options.video` field. Images are always matched on their visual content and have no options to configure. To choose which types of items to search, use the `filter.asset_type` field. If you provide options in the `search_options.video` field when the `filter.asset_type` field excludes videos, the platform returns a `400` error. If you omit this field, videos are matched on their visual content.
- `group_by` (enum, optional, default: none) — Controls how the platform groups matches in the response. - `none`: Returns individual matches ordered by relevance. - `item`: Groups matches under their parent item. **Default**: `none`.
  - Allowed values: `none`, `item`
- `page_size` (integer, optional, default: 10) — The maximum number of results per page. A result is one entry in the `data` array. With the `group_by` parameter set to its default of `none`, each result is an individual match: a video clip or an image. When set to `item`, each result is one item: a video with all its matching clips, or an image. **Default**: `10`. **Max**: `50`.
- `page_token` (string, optional) — Pagination token used to retrieve the next page of results. Omit it on the first request. To fetch the next page, set it to the `next_page_token` field returned in the previous response and send the request again. If a token is malformed or unrecognized, the platform returns a `400` error. If a token has expired, the platform returns a `410` error (make a new search request to obtain a fresh page token).
- `include_metadata` (boolean, optional, default: false) — Set to `true` to include metadata in each result. Each result includes a `metadata` object with these fields: - `system`: System-generated metadata, such as duration and resolution. - `user`: The custom metadata of the source asset. - `item`: The custom metadata of the knowledge store item.

## Response

### 200

The search completed successfully.

- `data` (list of SearchKnowledgeStoreHit, required) — Search results, ordered by relevance.
- `effective_search_options` (SearchKnowledgeStoreOptions, required) — The video options applied to this search, including any defaults. - **When the search includes videos**: this object contains a `video` field with the modalities used. - **When the search is limited to images** (the `filter.asset_type` field excludes videos): no video options apply, and this object is empty. Any option you omit is returned with its default value. For example, the `video` field shows `["visual"]` for modalities when you don't set `search_options.video`.
- `next_page_token` (string, optional) — Pagination token for the next page. Pass this value as the `page_token` parameter in your next request to retrieve more results. Absent when no more pages exist.

## Errors

### 400 Bad Request Error

The request has failed.

- `code` (string, optional) — A string representing the code associated with the error. See the [Error codes](/v1.3/api-reference/error-codes) page for details.
- `message` (string, optional) — A human-readable string describing the error, intended to be suitable for display in a user interface.

### 404 Not Found Error

The knowledge store does not exist, or the `filter.item_collection_id` field specifies an item collection that is not in the knowledge store.

- `code` (string, optional) — Represents the code associated with the error. See the [Error codes](/v1.3/api-reference/error-codes) page for details.
- `message` (string, optional) — A human-readable string describing the error.

### 410 Gone Error

The page token has expired. Page tokens are valid for a limited time; make a new search request to obtain a fresh first page and a new token.

- `code` (string, optional) — Represents the code associated with the error. See the [Error codes](/v1.3/api-reference/error-codes) page for details.
- `message` (string, optional) — A human-readable string describing the error.

### 422 Unprocessable Entity Error

The filter matches more than 10,000 items, or the `tags` field matches more than 100 tags. Narrow the filter and try again.

- `code` (string, optional) — Represents the code associated with the error. See the [Error codes](/v1.3/api-reference/error-codes) page for details.
- `message` (string, optional) — A human-readable string describing the error.

### 429 Too Many Requests Error

If the rate limit is reached, the platform returns an `HTTP 429 - Too Many Requests` error response. The response body is empty.

- `any`

## Types

### KnowledgeStoreSearchQuery

The search query.

- `text` (string, required) — Describe what you're searching for in natural language (Examples: `A person cooking pasta` or `aerial shots of a city at night`).

### SearchKnowledgeStoreFilter

Narrows results to specific items in the knowledge store. Omit the filter to search all items. You can filter with these fields: * `asset_type`: The type of item. Use `eq` to match one type. Use `in` to match any type in a list. * `item_id`: Specific items. Use `eq` to match one item or `in` to match any item in a list. Use `nin` to exclude any item in a list. You cannot use `eq` and `in` together. You can use `nin` on its own or with either `eq` or `in`. If an item is listed in `nin` and selected by `eq` or `in`, the platform excludes it. * `item_collection_id`: Specific item collections. Use `eq` to match the items in one item collection. Use `in` with a list of item collections to match the items in any of them. If an item collection is not in the knowledge store, the platform returns a `404` error with the `resource_not_exists` code. If the identifier of an item collection is not valid, the platform returns a `400` error with the `parameter_invalid` code. * `user_metadata`: Custom metadata. Map each key to `eq`, `in`, or inclusive numeric or date bounds with `gte` and `lte`. * `enrichment`: Enrichment values that the platform extracts. Map each key to the `eq` operator to match one value, or to the `in` operator to match any value in a list. * `created_at`: Creation time. Use `gte` to set the earliest time and `lte` to set the latest time. You can use one or both. * `location`: Capture location. Provide the center and the radius of a circle. * `tags`: Item tags. Map each key under `tags.metadata` to the `eq` operator to match one value, or to the `in` operator to match any value in a list. An item must match all of the fields and metadata keys that you specify. The `tags` field also limits which clips of an item the search returns. When you use any of the `item_collection_id`, `user_metadata`, `enrichment`, `created_at`, or `location` fields, the platform counts the items that match those conditions together, including metadata ranges and the items that you include or exclude with the `item_id` field. If more than 10,000 items match, the platform returns a `422` error with the `metadata_filter_too_broad` code. To reduce the count, add conditions or use the `item_id` field. The `asset_type` field does not reduce the count. When you use the `tags` field, the platform does not count items, and this limit does not apply. It counts the matching tags instead, as the `tags` field describes. Examples: ```json { "asset_type": { "eq": "video" } } ``` ```json { "asset_type": { "in": [ "video" ] }, "item_id": { "in": [ "ksi_069e9870-3c4d-7abc-9012-3456789abcde" ] } } ``` ```json { "user_metadata": { "category": { "eq": "tutorial" } }, "created_at": { "gte": "2026-09-01T00:00:00Z" } } ``` ```json { "location": { "latitude": 37.5665, "longitude": 126.978, "radius_meters": 5000 } } ``` ```json { "tags": { "metadata": { "event": { "eq": "goal" } } } } ```

- `asset_type` (AssetTypeFilter, optional) — Narrows results by type of item. Provide exactly one operator: `eq` to match one type, or `in` to match any of the listed types.
- `item_id` (ItemIdFilter, optional) — Narrows results to specific items. Use `eq` to match one item or `in` to match any item in a list. Use `nin` to exclude any item in a list. You cannot use `eq` and `in` together. You can use `nin` on its own or with either `eq` or `in`. If an item is listed in `nin` and selected by `eq` or `in`, the platform excludes it.
- `item_collection_id` (ItemCollectionIdFilter, optional) — Narrows results to the items in item collections. Provide exactly one operator: `eq` to match the items in one item collection, or `in` with a list of item collections to match the items in any of them. If an item collection has no items, the search returns no results. The search also returns no results when no item matches the other fields in the `filter` object.
- `user_metadata` (map from string to UserMetadataValueFilter, optional) — Narrows results by custom metadata. Map each key to `eq`, `in`, or an inclusive `gte`/`lte` range. You can specify 1 to 50 keys. An item must match every key. For each key, use exactly one of `eq` or `in`, or a range with `gte`, `lte`, or both. Do not combine `eq` or `in` with range bounds. Both range bounds must be numbers or both must be RFC 3339 timestamps with a timezone, and `gte` must not exceed `lte`. If you set both bounds, a single value must satisfy both. Numeric ranges match numeric scalars, excluding numeric strings and booleans. Date ranges compare times with their timezone offsets. A timestamp must include a time and a timezone: use `Z` or an offset such as `+09:00`. For example, `2026-09-29T00:00:00Z` and `2026-09-29T09:00:00+09:00` represent the same time. A date without a time, such as `2026-09-29`, or a timestamp without a timezone returns a `400` error. Missing keys, malformed date values, nulls, and arrays in stored metadata do not match a range. A publication date you stored in custom metadata can be filtered here; `created_at` filters creation time. A key matches the custom metadata of the source asset (the `metadata` field of the knowledge store item) and the custom metadata of the knowledge store item (the `item_metadata` field). An item matches a key when the value matches in either field. For the names of these fields in search results, see the [Custom metadata field names](/v1.3/api-reference/knowledge-store-items/the-knowledge-store-item-object#custom-metadata-field-names) section on **The knowledge store item object** page.
- `enrichment` (map from string to MetadataValueFilter, optional) — Narrows results by enrichment values. The platform extracts these values as the enrichment configuration of the knowledge store defines (the `ingestion_config.enrichment_config` field). Map each top-level property that the enrichment configuration defines to an object with exactly one of the `eq` or `in` operators. You can specify 1 to 50 keys. If you specify a key that the enrichment configuration does not define, the platform returns a `400` error. The `granularity` keyword of a property sets how often the platform extracts its value. The keyword also sets which items the key matches: - `video`: One value for each video. The key matches video items only. - `image`: One value for each image. The key matches image items only. - `shot`: One value for each shot of a video. A shot is a continuous part of a video between two scene changes. The key matches video items only. If you specify more than one `shot` key, one shot must have all of the values. For example, a filter with the keys `topic` and `sentiment` at the `shot` granularity matches a video only when one shot has both values. An item must match all of the keys that you specify. A filter with a `video` key and an `image` key matches no items, because an item is a video or an image. Use the filter to choose which items to search. The search can return any clip of a matching item, including clips that do not match the filter.
- `created_at` (CreatedAtFilter, optional) — Narrows results by the creation time of the item. Use `gte` to set the earliest time and `lte` to set the latest time. You can use one or both. When you use both, the `gte` time must be equal to or earlier than the `lte` time. The creation time is the time when you create the item with the [`POST`](/v1.3/api-reference/knowledge-store-items/create) method of the `/knowledge-stores/{knowledge_store_id}/items` endpoint. It is not the time when the item reaches the `ready` status. To read the creation time of an item, use the [`GET`](/v1.3/api-reference/knowledge-store-items/retrieve) method of the `/knowledge-stores/{knowledge_store_id}/items/{item_id}` endpoint. The time is in the `created_at` field.
- `location` (GeoCircleFilter, optional) — Narrows results to items captured within a circle. An item matches when the GPS coordinates embedded in its source media are within `radius_meters` of the center, measured as great-circle distance. Items with no coordinates never match. To read the GPS coordinates of the source media, use the [`GET`](/v1.3/api-reference/manage-assets/retrieve) method of the `/assets/{asset_id}` endpoint. The coordinates are the `geospatial_latitude` and `geospatial_longitude` fields of the `technical_metadata` object.
- `tags` (TagFilter, optional) — Narrows results to the moments and ranges that matching tags mark on video items. A tag matches when its `tag_metadata` field matches the `metadata` field. Only video items have tags, so images do not appear in the results. The search returns only the clips within a matching tag: * For a tag on a range, a clip matches when it lies entirely within the range. A clip that extends past either end of the range does not appear in the results. * For a tag on a single moment, a clip matches when it contains that moment. A clip within more than one matching tag appears once. With the `group_by` parameter set to `item`, each item groups only its clips within matching tags. When you specify other fields of the filter, a tag counts only when its item matches every other field. The `asset_type` field does not reduce the count. If more than 100 tags match, the platform returns a `422` error with the `metadata_filter_too_broad` code. To tag a moment or a range of a video item, use the [`POST`](/v1.3/api-reference/knowledge-store-items/item-tags/create) method of the `/knowledge-stores/{knowledge_store_id}/items/{item_id}/tags` endpoint.

### SearchKnowledgeStoreOptions

Specifies how videos are matched. Videos are the only type of item with configurable options, set in the `search_options.video` field. Images are always matched on their visual content and have no options to configure. To choose which types of items to search, use the `filter.asset_type` field. If you provide options in the `search_options.video` field when the `filter.asset_type` field excludes videos, the platform returns a `400` error. If you omit this field, videos are matched on their visual content.

- `video` (VideoSearchOptions, optional) — Options that control how videos are matched. By default, videos are matched on their visual content.

### SearchKnowledgeStoreHit

A single result in the search response. The fields present depend on the `asset_type` field.

- `asset_type`: `video` (video)
  - `item_id` (string, required) — The unique identifier of the knowledge store item.
  - `matches` (list of VideoMatch, required) — Matching clips from this video, ordered by relevance. - When `group_by` is `none`: Contains one entry — the matching clip. - When `group_by` is `item`: Contains all matching clips from this video, with the best match first.
  - `rank` (integer, required) — The relevance position of this result, starting at 1. When `group_by` is `item`, videos are ordered by their most relevant clip.
  - `metadata` (VideoSearchItemMetadata, optional) — Metadata attached to the item. Returned when you set the `include_metadata` parameter to `true`.
- `asset_type`: `image` (image)
  - `item_id` (string, required) — The unique identifier of the knowledge store item.
  - `rank` (integer, required) — The relevance position of this result, starting at 1.
  - `metadata` (ImageSearchItemMetadata, optional) — Metadata attached to the item. Returned when you set the `include_metadata` parameter to `true`.

### AssetTypeFilter

Narrows results by type of item. Provide exactly one operator: `eq` to match one type, or `in` to match any of the listed types.

- `eq` (enum, optional) — Match items that have this value for `asset_type`.
  - Allowed values: `video`, `image`
- `in` (list of enum, optional) — Match items that have any of these values for `asset_type`.
  - Allowed values: `video`, `image`

### ItemIdFilter

Narrows results to specific items. Use `eq` to match one item or `in` to match any item in a list. Use `nin` to exclude any item in a list. You cannot use `eq` and `in` together. You can use `nin` on its own or with either `eq` or `in`. If an item is listed in `nin` and selected by `eq` or `in`, the platform excludes it.

- `eq` (string, optional) — Match the item with this identifier.
- `in` (list of string, optional) — Match any item with an identifier in this list.
- `nin` (list of string, optional) — Exclude every clip or image belonging to these items. You can list 1 to 20,000 item IDs.

### ItemCollectionIdFilter

Narrows results to the items in item collections. Provide exactly one operator: `eq` to match the items in one item collection, or `in` with a list of item collections to match the items in any of them. If an item collection has no items, the search returns no results. The search also returns no results when no item matches the other fields in the `filter` object.

- `eq` (string, optional) — Match the items in the item collection with this identifier. You retrieve the identifier when you create an item collection.
- `in` (list of string, optional) — Match the items in any item collection with an identifier from this list.

### UserMetadataValueFilter

Match one key with `eq`, `in`, or inclusive `gte`/`lte` bounds. Equality and membership cannot be combined with ranges. Both range bounds must be numbers or both must be RFC 3339 timestamps with a timezone, and `gte` must not exceed `lte`. Numeric ranges match numeric scalars, excluding numeric strings and booleans. Date ranges compare instants, including timezone offsets. Missing values, malformed dates, nulls, and arrays do not match a range. A publication date stored in metadata can be filtered here; `created_at` filters creation time.

- `eq` (MetadataScalarValue, optional) — Match when the key has this value. The value must have the same type as the stored value for the key. For example, the number `2026` does not match the string `"2026"`. If the key holds a list, it matches when the list contains the value.
- `in` (list of MetadataScalarValue, optional) — Match when the key has any of these values. You can specify 1 to 100 values. Each value follows the rules for the `eq` operator. For example, `["tutorial", "guide"]` matches the value `tutorial` or `guide`.
- `gte` (MetadataRangeBound, optional) — Inclusive lower bound. Use a number or an RFC 3339 timestamp with a timezone, such as `2026-09-29T00:00:00Z` or `2026-09-29T09:00:00+09:00`.
- `lte` (MetadataRangeBound, optional) — Inclusive upper bound. Use a number or an RFC 3339 timestamp with a timezone, such as `2026-09-29T00:00:00Z` or `2026-09-29T09:00:00+09:00`.

### MetadataValueFilter

Narrows results by the value of one key. Provide exactly one operator: `eq` to match one value, or `in` to match any of the listed values.

- `eq` (MetadataScalarValue, optional) — Match when the key has this value. The value must have the same type as the stored value for the key. For example, the number `2026` does not match the string `"2026"`. If the key holds a list, it matches when the list contains the value.
- `in` (list of MetadataScalarValue, optional) — Match when the key has any of these values. You can specify 1 to 100 values. Each value follows the rules for the `eq` operator. For example, `["tutorial", "guide"]` matches the value `tutorial` or `guide`.

### CreatedAtFilter

Narrows results by the creation time of the item. Use `gte` to set the earliest time and `lte` to set the latest time. You can use one or both. When you use both, the `gte` time must be equal to or earlier than the `lte` time. The creation time is the time when you create the item with the [`POST`](/v1.3/api-reference/knowledge-store-items/create) method of the `/knowledge-stores/{knowledge_store_id}/items` endpoint. It is not the time when the item reaches the `ready` status. To read the creation time of an item, use the [`GET`](/v1.3/api-reference/knowledge-store-items/retrieve) method of the `/knowledge-stores/{knowledge_store_id}/items/{item_id}` endpoint. The time is in the `created_at` field.

- `gte` (string, optional) — Match items created at or after this time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ").
- `lte` (string, optional) — Match items created at or before this time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ").

### GeoCircleFilter

Narrows results to items captured within a circle. An item matches when the GPS coordinates embedded in its source media are within `radius_meters` of the center, measured as great-circle distance. Items with no coordinates never match. To read the GPS coordinates of the source media, use the [`GET`](/v1.3/api-reference/manage-assets/retrieve) method of the `/assets/{asset_id}` endpoint. The coordinates are the `geospatial_latitude` and `geospatial_longitude` fields of the `technical_metadata` object.

- `latitude` (double, required) — The latitude of the center, in decimal degrees. The value must be between -90 and 90.
- `longitude` (double, required) — The longitude of the center, in decimal degrees. The value must be between -180 and 180.
- `radius_meters` (double, required) — The radius of the circle, in meters. The value must be greater than 0 and at most 20,037,508.

### TagFilter

Narrows results to the moments and ranges that matching tags mark on video items. A tag matches when its `tag_metadata` field matches the `metadata` field. Only video items have tags, so images do not appear in the results. The search returns only the clips within a matching tag: * For a tag on a range, a clip matches when it lies entirely within the range. A clip that extends past either end of the range does not appear in the results. * For a tag on a single moment, a clip matches when it contains that moment. A clip within more than one matching tag appears once. With the `group_by` parameter set to `item`, each item groups only its clips within matching tags. When you specify other fields of the filter, a tag counts only when its item matches every other field. The `asset_type` field does not reduce the count. If more than 100 tags match, the platform returns a `422` error with the `metadata_filter_too_broad` code. To tag a moment or a range of a video item, use the [`POST`](/v1.3/api-reference/knowledge-store-items/item-tags/create) method of the `/knowledge-stores/{knowledge_store_id}/items/{item_id}/tags` endpoint.

- `metadata` (map from string to MetadataValueFilter, required) — The metadata to match against the `tag_metadata` field of each tag. Map each key to an object with exactly one of `eq` or `in`. Specify 1 to 50 keys. When you specify more than one key, every key must match on the same tag. A value is a string, a number, or a boolean. The platform matches it with the JSON type the tag stores, so `2026` does not match a tag that stores `"2026"`. A key that stores a list matches when the list contains the value.

### VideoSearchOptions

Options that control how videos are matched. By default, videos are matched on their visual content.

- `modalities` (list of enum, required) — The video modalities used for searching. Available options: - `visual`: Searches visual content. - `audio`: Searches audio content, including speech and non-speech sounds. You can combine multiple modalities to broaden your search. For example, to search both visual content and audio, set the `modalities` parameter to `["visual", "audio"]`. For guidance, see [Search options](/v1.3/docs/concepts/modalities#search-options).
  - Allowed values: `visual`, `audio`

### VideoMatch

A matching clip from a video.

- `start_sec` (double, required) — The clip start offset, in seconds, within the source video.
- `end_sec` (double, required) — The clip end offset, in seconds, within the source video.
- `modalities` (list of enum, required) — The modalities that matched in this clip.
  - Allowed values: `visual`, `audio`
- `transcription` (string, optional) — The spoken words in the clip. Returned when spoken-word data is available for the clip, regardless of which modalities matched.

### VideoSearchItemMetadata

Metadata attached to a video knowledge store item in search results.

- `system` (VideoSearchSystemMetadata, optional) — System-generated metadata for the source video.
- `user` (map from string to KnowledgeStoreMetadataValue, optional) — The custom metadata of the source asset. The `metadata` field of the knowledge store item contains the same metadata.
- `item` (map from string to KnowledgeStoreMetadataValue, optional) — The custom metadata of the knowledge store item. It is separate from the custom metadata of the source asset. A change to the custom metadata of the source asset does not change this field. The same key can have different values in the `user` field and in the `item` field. The `item_metadata` field of the knowledge store item contains the same metadata. This field is absent when no item metadata has been set.

### ImageSearchItemMetadata

Metadata attached to an image knowledge store item in search results.

- `system` (ImageSearchSystemMetadata, optional) — System-generated metadata for the source image.
- `user` (map from string to KnowledgeStoreMetadataValue, optional) — The custom metadata of the source asset. The `metadata` field of the knowledge store item contains the same metadata.
- `item` (map from string to KnowledgeStoreMetadataValue, optional) — The custom metadata of the knowledge store item. It is separate from the custom metadata of the source asset. A change to the custom metadata of the source asset does not change this field. The same key can have different values in the `user` field and in the `item` field. The `item_metadata` field of the knowledge store item contains the same metadata. This field is absent when no item metadata has been set.

### MetadataScalarValue

A value to match: a string, a number, or a boolean.

- string
- integer
- double
- boolean

### MetadataRangeBound

A numeric scalar or an RFC 3339 timestamp with a timezone.

- integer
- double
- string

### VideoSearchSystemMetadata

System-generated metadata for a video item in search results.

- `duration` (double, optional) — The duration of the video in seconds.
- `width` (integer, optional) — The width of the video in pixels.
- `height` (integer, optional) — The height of the video in pixels.
- `size` (long, optional) — The file size of the video in bytes.

### KnowledgeStoreMetadataValue

A single custom-metadata value: a string, a number, a boolean, or an array of strings. The value keeps the JSON type sent; a nested object, an array containing anything other than strings, and a null value are rejected. An integer must fit in 53 bits (-9007199254740991 to 9007199254740991). A wider integer, or an identifier that must be preserved verbatim, must be sent as a string.

- string
- integer
- double
- boolean
- list of string

### ImageSearchSystemMetadata

System-generated metadata for an image item in search results.

- `width` (integer, optional) — The width of the image in pixels.
- `height` (integer, optional) — The height of the image in pixels.
- `size` (long, optional) — The file size of the image in bytes.

## Examples

### Video and image results

**Response**

```json
{
  "data": [
    {
      "asset_type": "video",
      "item_id": "ksi_069e9870-3c4d-7abc-9012-3456789abcde",
      "matches": [
        {
          "start_sec": 12.5,
          "end_sec": 18.25,
          "modalities": [
            "visual"
          ],
          "transcription": "Add a pinch of salt to the boiling water."
        }
      ],
      "rank": 1
    },
    {
      "asset_type": "image",
      "item_id": "ksi_069e9871-4a5b-7cde-9012-3456789abcde",
      "rank": 2
    }
  ],
  "effective_search_options": {
    "video": {
      "modalities": [
        "visual",
        "audio"
      ]
    }
  },
  "next_page_token": "eyJwYWdlIjoyfQ=="
}
```

**SDK Code**

```python Video and image results
import requests

url = "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search"

headers = {"x-api-key": "<apiKey>"}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript Video and image results
const url = 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search';
const options = {method: 'POST', headers: {'x-api-key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Video and image results
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("x-api-key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Video and image results
require 'uri'
require 'net/http'

url = URI("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java Video and image results
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")
  .header("x-api-key", "<apiKey>")
  .asString();
```

```php Video and image results
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Video and image results
using RestSharp;

var client = new RestClient("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift Video and image results
import Foundation

let headers = ["x-api-key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Default search (search_options omitted)

**Response**

```json
{
  "data": [
    {
      "asset_type": "video",
      "item_id": "ksi_069e9870-3c4d-7abc-9012-3456789abcde",
      "matches": [
        {
          "start_sec": 12.5,
          "end_sec": 18.25,
          "modalities": [
            "visual"
          ]
        }
      ],
      "rank": 1
    },
    {
      "asset_type": "image",
      "item_id": "ksi_069e9871-4a5b-7cde-9012-3456789abcde",
      "rank": 2
    }
  ],
  "effective_search_options": {
    "video": {
      "modalities": [
        "visual"
      ]
    }
  }
}
```

**SDK Code**

```python Default search (search_options omitted)
import requests

url = "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search"

headers = {"x-api-key": "<apiKey>"}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript Default search (search_options omitted)
const url = 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search';
const options = {method: 'POST', headers: {'x-api-key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Default search (search_options omitted)
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("x-api-key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Default search (search_options omitted)
require 'uri'
require 'net/http'

url = URI("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java Default search (search_options omitted)
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")
  .header("x-api-key", "<apiKey>")
  .asString();
```

```php Default search (search_options omitted)
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Default search (search_options omitted)
using RestSharp;

var client = new RestClient("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift Default search (search_options omitted)
import Foundation

let headers = ["x-api-key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Search all items, with custom video modalities

**Request**

```json
{
  "query": {
    "text": "A person cooking pasta"
  },
  "search_options": {
    "video": {
      "modalities": [
        "visual",
        "audio"
      ]
    }
  },
  "group_by": "none",
  "page_size": 10
}
```

**Response**

```json
{
  "data": [
    {
      "asset_type": "video",
      "item_id": "ksi_069e9870-3c4d-7abc-9012-3456789abcde",
      "matches": [
        {
          "start_sec": 12.5,
          "end_sec": 18.25,
          "modalities": [
            "visual"
          ],
          "transcription": "Add a pinch of salt to the boiling water."
        }
      ],
      "rank": 1
    },
    {
      "asset_type": "image",
      "item_id": "ksi_069e9871-4a5b-7cde-9012-3456789abcde",
      "rank": 2
    }
  ],
  "effective_search_options": {
    "video": {
      "modalities": [
        "visual",
        "audio"
      ]
    }
  },
  "next_page_token": "eyJwYWdlIjoyfQ=="
}
```

**SDK Code**

```python Search all items, with custom video modalities
import requests

url = "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search"

payload = {
    "query": { "text": "A person cooking pasta" },
    "search_options": { "video": { "modalities": ["visual", "audio"] } },
    "group_by": "none",
    "page_size": 10
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Search all items, with custom video modalities
const url = 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"query":{"text":"A person cooking pasta"},"search_options":{"video":{"modalities":["visual","audio"]}},"group_by":"none","page_size":10}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Search all items, with custom video modalities
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search"

	payload := strings.NewReader("{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"search_options\": {\n    \"video\": {\n      \"modalities\": [\n        \"visual\",\n        \"audio\"\n      ]\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Search all items, with custom video modalities
require 'uri'
require 'net/http'

url = URI("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"search_options\": {\n    \"video\": {\n      \"modalities\": [\n        \"visual\",\n        \"audio\"\n      ]\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}"

response = http.request(request)
puts response.read_body
```

```java Search all items, with custom video modalities
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"search_options\": {\n    \"video\": {\n      \"modalities\": [\n        \"visual\",\n        \"audio\"\n      ]\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}")
  .asString();
```

```php Search all items, with custom video modalities
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search', [
  'body' => '{
  "query": {
    "text": "A person cooking pasta"
  },
  "search_options": {
    "video": {
      "modalities": [
        "visual",
        "audio"
      ]
    }
  },
  "group_by": "none",
  "page_size": 10
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Search all items, with custom video modalities
using RestSharp;

var client = new RestClient("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"search_options\": {\n    \"video\": {\n      \"modalities\": [\n        \"visual\",\n        \"audio\"\n      ]\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Search all items, with custom video modalities
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "query": ["text": "A person cooking pasta"],
  "search_options": ["video": ["modalities": ["visual", "audio"]]],
  "group_by": "none",
  "page_size": 10
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Search video items only

**Request**

```json
{
  "query": {
    "text": "A person cooking pasta"
  },
  "filter": {
    "asset_type": {
      "in": [
        "video"
      ]
    }
  },
  "search_options": {
    "video": {
      "modalities": [
        "visual",
        "audio"
      ]
    }
  },
  "group_by": "none",
  "page_size": 10
}
```

**Response**

```json
{
  "data": [
    {
      "asset_type": "video",
      "item_id": "ksi_069e9870-3c4d-7abc-9012-3456789abcde",
      "matches": [
        {
          "start_sec": 12.5,
          "end_sec": 18.25,
          "modalities": [
            "visual"
          ],
          "transcription": "Add a pinch of salt to the boiling water."
        }
      ],
      "rank": 1
    },
    {
      "asset_type": "image",
      "item_id": "ksi_069e9871-4a5b-7cde-9012-3456789abcde",
      "rank": 2
    }
  ],
  "effective_search_options": {
    "video": {
      "modalities": [
        "visual",
        "audio"
      ]
    }
  },
  "next_page_token": "eyJwYWdlIjoyfQ=="
}
```

**SDK Code**

```python Search video items only
import requests

url = "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search"

payload = {
    "query": { "text": "A person cooking pasta" },
    "filter": { "asset_type": { "in": ["video"] } },
    "search_options": { "video": { "modalities": ["visual", "audio"] } },
    "group_by": "none",
    "page_size": 10
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Search video items only
const url = 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"query":{"text":"A person cooking pasta"},"filter":{"asset_type":{"in":["video"]}},"search_options":{"video":{"modalities":["visual","audio"]}},"group_by":"none","page_size":10}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Search video items only
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search"

	payload := strings.NewReader("{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"filter\": {\n    \"asset_type\": {\n      \"in\": [\n        \"video\"\n      ]\n    }\n  },\n  \"search_options\": {\n    \"video\": {\n      \"modalities\": [\n        \"visual\",\n        \"audio\"\n      ]\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Search video items only
require 'uri'
require 'net/http'

url = URI("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"filter\": {\n    \"asset_type\": {\n      \"in\": [\n        \"video\"\n      ]\n    }\n  },\n  \"search_options\": {\n    \"video\": {\n      \"modalities\": [\n        \"visual\",\n        \"audio\"\n      ]\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}"

response = http.request(request)
puts response.read_body
```

```java Search video items only
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"filter\": {\n    \"asset_type\": {\n      \"in\": [\n        \"video\"\n      ]\n    }\n  },\n  \"search_options\": {\n    \"video\": {\n      \"modalities\": [\n        \"visual\",\n        \"audio\"\n      ]\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}")
  .asString();
```

```php Search video items only
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search', [
  'body' => '{
  "query": {
    "text": "A person cooking pasta"
  },
  "filter": {
    "asset_type": {
      "in": [
        "video"
      ]
    }
  },
  "search_options": {
    "video": {
      "modalities": [
        "visual",
        "audio"
      ]
    }
  },
  "group_by": "none",
  "page_size": 10
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Search video items only
using RestSharp;

var client = new RestClient("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"filter\": {\n    \"asset_type\": {\n      \"in\": [\n        \"video\"\n      ]\n    }\n  },\n  \"search_options\": {\n    \"video\": {\n      \"modalities\": [\n        \"visual\",\n        \"audio\"\n      ]\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Search video items only
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "query": ["text": "A person cooking pasta"],
  "filter": ["asset_type": ["in": ["video"]]],
  "search_options": ["video": ["modalities": ["visual", "audio"]]],
  "group_by": "none",
  "page_size": 10
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Search items captured within 5 km of a point

**Request**

```json
{
  "query": {
    "text": "A person cooking pasta"
  },
  "filter": {
    "location": {
      "latitude": 37.5665,
      "longitude": 126.978,
      "radius_meters": 5000
    }
  },
  "group_by": "none",
  "page_size": 10
}
```

**Response**

```json
{
  "data": [
    {
      "asset_type": "video",
      "item_id": "ksi_069e9870-3c4d-7abc-9012-3456789abcde",
      "matches": [
        {
          "start_sec": 12.5,
          "end_sec": 18.25,
          "modalities": [
            "visual"
          ],
          "transcription": "Add a pinch of salt to the boiling water."
        }
      ],
      "rank": 1
    },
    {
      "asset_type": "image",
      "item_id": "ksi_069e9871-4a5b-7cde-9012-3456789abcde",
      "rank": 2
    }
  ],
  "effective_search_options": {
    "video": {
      "modalities": [
        "visual",
        "audio"
      ]
    }
  },
  "next_page_token": "eyJwYWdlIjoyfQ=="
}
```

**SDK Code**

```python Search items captured within 5 km of a point
import requests

url = "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search"

payload = {
    "query": { "text": "A person cooking pasta" },
    "filter": { "location": {
            "latitude": 37.5665,
            "longitude": 126.978,
            "radius_meters": 5000
        } },
    "group_by": "none",
    "page_size": 10
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Search items captured within 5 km of a point
const url = 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"query":{"text":"A person cooking pasta"},"filter":{"location":{"latitude":37.5665,"longitude":126.978,"radius_meters":5000}},"group_by":"none","page_size":10}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Search items captured within 5 km of a point
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search"

	payload := strings.NewReader("{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"filter\": {\n    \"location\": {\n      \"latitude\": 37.5665,\n      \"longitude\": 126.978,\n      \"radius_meters\": 5000\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Search items captured within 5 km of a point
require 'uri'
require 'net/http'

url = URI("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"filter\": {\n    \"location\": {\n      \"latitude\": 37.5665,\n      \"longitude\": 126.978,\n      \"radius_meters\": 5000\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}"

response = http.request(request)
puts response.read_body
```

```java Search items captured within 5 km of a point
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"filter\": {\n    \"location\": {\n      \"latitude\": 37.5665,\n      \"longitude\": 126.978,\n      \"radius_meters\": 5000\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}")
  .asString();
```

```php Search items captured within 5 km of a point
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search', [
  'body' => '{
  "query": {
    "text": "A person cooking pasta"
  },
  "filter": {
    "location": {
      "latitude": 37.5665,
      "longitude": 126.978,
      "radius_meters": 5000
    }
  },
  "group_by": "none",
  "page_size": 10
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Search items captured within 5 km of a point
using RestSharp;

var client = new RestClient("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"filter\": {\n    \"location\": {\n      \"latitude\": 37.5665,\n      \"longitude\": 126.978,\n      \"radius_meters\": 5000\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Search items captured within 5 km of a point
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "query": ["text": "A person cooking pasta"],
  "filter": ["location": [
      "latitude": 37.5665,
      "longitude": 126.978,
      "radius_meters": 5000
    ]],
  "group_by": "none",
  "page_size": 10
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Default search across all items (search_options omitted)

**Request**

```json
{
  "query": {
    "text": "A person cooking pasta"
  },
  "group_by": "none",
  "page_size": 10
}
```

**Response**

```json
{
  "data": [
    {
      "asset_type": "video",
      "item_id": "ksi_069e9870-3c4d-7abc-9012-3456789abcde",
      "matches": [
        {
          "start_sec": 12.5,
          "end_sec": 18.25,
          "modalities": [
            "visual"
          ],
          "transcription": "Add a pinch of salt to the boiling water."
        }
      ],
      "rank": 1
    },
    {
      "asset_type": "image",
      "item_id": "ksi_069e9871-4a5b-7cde-9012-3456789abcde",
      "rank": 2
    }
  ],
  "effective_search_options": {
    "video": {
      "modalities": [
        "visual",
        "audio"
      ]
    }
  },
  "next_page_token": "eyJwYWdlIjoyfQ=="
}
```

**SDK Code**

```python Default search across all items (search_options omitted)
import requests

url = "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search"

payload = {
    "query": { "text": "A person cooking pasta" },
    "group_by": "none",
    "page_size": 10
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Default search across all items (search_options omitted)
const url = 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"query":{"text":"A person cooking pasta"},"group_by":"none","page_size":10}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Default search across all items (search_options omitted)
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search"

	payload := strings.NewReader("{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Default search across all items (search_options omitted)
require 'uri'
require 'net/http'

url = URI("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}"

response = http.request(request)
puts response.read_body
```

```java Default search across all items (search_options omitted)
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}")
  .asString();
```

```php Default search across all items (search_options omitted)
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search', [
  'body' => '{
  "query": {
    "text": "A person cooking pasta"
  },
  "group_by": "none",
  "page_size": 10
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Default search across all items (search_options omitted)
using RestSharp;

var client = new RestClient("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Default search across all items (search_options omitted)
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "query": ["text": "A person cooking pasta"],
  "group_by": "none",
  "page_size": 10
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Search items by custom metadata, enrichment values, and creation time

**Request**

```json
{
  "query": {
    "text": "A person cooking pasta"
  },
  "filter": {
    "user_metadata": {
      "category": {
        "eq": "tutorial"
      }
    },
    "enrichment": {
      "detected_topic": {
        "eq": "cooking"
      }
    },
    "created_at": {
      "gte": "2026-09-01T00:00:00Z"
    }
  },
  "group_by": "none",
  "page_size": 10
}
```

**Response**

```json
{
  "data": [
    {
      "asset_type": "video",
      "item_id": "ksi_069e9870-3c4d-7abc-9012-3456789abcde",
      "matches": [
        {
          "start_sec": 12.5,
          "end_sec": 18.25,
          "modalities": [
            "visual"
          ],
          "transcription": "Add a pinch of salt to the boiling water."
        }
      ],
      "rank": 1
    },
    {
      "asset_type": "image",
      "item_id": "ksi_069e9871-4a5b-7cde-9012-3456789abcde",
      "rank": 2
    }
  ],
  "effective_search_options": {
    "video": {
      "modalities": [
        "visual",
        "audio"
      ]
    }
  },
  "next_page_token": "eyJwYWdlIjoyfQ=="
}
```

**SDK Code**

```python Search items by custom metadata, enrichment values, and creation time
import requests

url = "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search"

payload = {
    "query": { "text": "A person cooking pasta" },
    "filter": {
        "user_metadata": { "category": { "eq": "tutorial" } },
        "enrichment": { "detected_topic": { "eq": "cooking" } },
        "created_at": { "gte": "2026-09-01T00:00:00Z" }
    },
    "group_by": "none",
    "page_size": 10
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Search items by custom metadata, enrichment values, and creation time
const url = 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"query":{"text":"A person cooking pasta"},"filter":{"user_metadata":{"category":{"eq":"tutorial"}},"enrichment":{"detected_topic":{"eq":"cooking"}},"created_at":{"gte":"2026-09-01T00:00:00Z"}},"group_by":"none","page_size":10}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Search items by custom metadata, enrichment values, and creation time
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search"

	payload := strings.NewReader("{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"filter\": {\n    \"user_metadata\": {\n      \"category\": {\n        \"eq\": \"tutorial\"\n      }\n    },\n    \"enrichment\": {\n      \"detected_topic\": {\n        \"eq\": \"cooking\"\n      }\n    },\n    \"created_at\": {\n      \"gte\": \"2026-09-01T00:00:00Z\"\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Search items by custom metadata, enrichment values, and creation time
require 'uri'
require 'net/http'

url = URI("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"filter\": {\n    \"user_metadata\": {\n      \"category\": {\n        \"eq\": \"tutorial\"\n      }\n    },\n    \"enrichment\": {\n      \"detected_topic\": {\n        \"eq\": \"cooking\"\n      }\n    },\n    \"created_at\": {\n      \"gte\": \"2026-09-01T00:00:00Z\"\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}"

response = http.request(request)
puts response.read_body
```

```java Search items by custom metadata, enrichment values, and creation time
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"filter\": {\n    \"user_metadata\": {\n      \"category\": {\n        \"eq\": \"tutorial\"\n      }\n    },\n    \"enrichment\": {\n      \"detected_topic\": {\n        \"eq\": \"cooking\"\n      }\n    },\n    \"created_at\": {\n      \"gte\": \"2026-09-01T00:00:00Z\"\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}")
  .asString();
```

```php Search items by custom metadata, enrichment values, and creation time
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search', [
  'body' => '{
  "query": {
    "text": "A person cooking pasta"
  },
  "filter": {
    "user_metadata": {
      "category": {
        "eq": "tutorial"
      }
    },
    "enrichment": {
      "detected_topic": {
        "eq": "cooking"
      }
    },
    "created_at": {
      "gte": "2026-09-01T00:00:00Z"
    }
  },
  "group_by": "none",
  "page_size": 10
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Search items by custom metadata, enrichment values, and creation time
using RestSharp;

var client = new RestClient("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"query\": {\n    \"text\": \"A person cooking pasta\"\n  },\n  \"filter\": {\n    \"user_metadata\": {\n      \"category\": {\n        \"eq\": \"tutorial\"\n      }\n    },\n    \"enrichment\": {\n      \"detected_topic\": {\n        \"eq\": \"cooking\"\n      }\n    },\n    \"created_at\": {\n      \"gte\": \"2026-09-01T00:00:00Z\"\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Search items by custom metadata, enrichment values, and creation time
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "query": ["text": "A person cooking pasta"],
  "filter": [
    "user_metadata": ["category": ["eq": "tutorial"]],
    "enrichment": ["detected_topic": ["eq": "cooking"]],
    "created_at": ["gte": "2026-09-01T00:00:00Z"]
  ],
  "group_by": "none",
  "page_size": 10
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Search only the moments that matching tags mark

**Request**

```json
{
  "query": {
    "text": "A player celebrating"
  },
  "filter": {
    "tags": {
      "metadata": {
        "event": {
          "eq": "goal"
        }
      }
    }
  },
  "group_by": "none",
  "page_size": 10
}
```

**Response**

```json
{
  "data": [
    {
      "asset_type": "video",
      "item_id": "ksi_069e9870-3c4d-7abc-9012-3456789abcde",
      "matches": [
        {
          "start_sec": 12.5,
          "end_sec": 18.25,
          "modalities": [
            "visual"
          ],
          "transcription": "Add a pinch of salt to the boiling water."
        }
      ],
      "rank": 1
    },
    {
      "asset_type": "image",
      "item_id": "ksi_069e9871-4a5b-7cde-9012-3456789abcde",
      "rank": 2
    }
  ],
  "effective_search_options": {
    "video": {
      "modalities": [
        "visual",
        "audio"
      ]
    }
  },
  "next_page_token": "eyJwYWdlIjoyfQ=="
}
```

**SDK Code**

```python Search only the moments that matching tags mark
import requests

url = "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search"

payload = {
    "query": { "text": "A player celebrating" },
    "filter": { "tags": { "metadata": { "event": { "eq": "goal" } } } },
    "group_by": "none",
    "page_size": 10
}
headers = {
    "x-api-key": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Search only the moments that matching tags mark
const url = 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search';
const options = {
  method: 'POST',
  headers: {'x-api-key': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"query":{"text":"A player celebrating"},"filter":{"tags":{"metadata":{"event":{"eq":"goal"}}}},"group_by":"none","page_size":10}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Search only the moments that matching tags mark
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search"

	payload := strings.NewReader("{\n  \"query\": {\n    \"text\": \"A player celebrating\"\n  },\n  \"filter\": {\n    \"tags\": {\n      \"metadata\": {\n        \"event\": {\n          \"eq\": \"goal\"\n        }\n      }\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Search only the moments that matching tags mark
require 'uri'
require 'net/http'

url = URI("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": {\n    \"text\": \"A player celebrating\"\n  },\n  \"filter\": {\n    \"tags\": {\n      \"metadata\": {\n        \"event\": {\n          \"eq\": \"goal\"\n        }\n      }\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}"

response = http.request(request)
puts response.read_body
```

```java Search only the moments that matching tags mark
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")
  .header("x-api-key", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": {\n    \"text\": \"A player celebrating\"\n  },\n  \"filter\": {\n    \"tags\": {\n      \"metadata\": {\n        \"event\": {\n          \"eq\": \"goal\"\n        }\n      }\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}")
  .asString();
```

```php Search only the moments that matching tags mark
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search', [
  'body' => '{
  "query": {
    "text": "A player celebrating"
  },
  "filter": {
    "tags": {
      "metadata": {
        "event": {
          "eq": "goal"
        }
      }
    }
  },
  "group_by": "none",
  "page_size": 10
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp Search only the moments that matching tags mark
using RestSharp;

var client = new RestClient("https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"query\": {\n    \"text\": \"A player celebrating\"\n  },\n  \"filter\": {\n    \"tags\": {\n      \"metadata\": {\n        \"event\": {\n          \"eq\": \"goal\"\n        }\n      }\n    }\n  },\n  \"group_by\": \"none\",\n  \"page_size\": 10\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Search only the moments that matching tags mark
import Foundation

let headers = [
  "x-api-key": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "query": ["text": "A player celebrating"],
  "filter": ["tags": ["metadata": ["event": ["eq": "goal"]]]],
  "group_by": "none",
  "page_size": 10
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/knowledge-stores/ks_069e9869-1ea3-7481-8000-dae72bf6be6e/search")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```