Agents (Research preview)Search a knowledge store

Search a knowledge store

This method searches a knowledge store using natural language and returns matching video clips and images ranked by relevance. Provide your natural-language query in the `query.text` field. Use the `filter` parameter to choose which items to search: by type of item (the `asset_type` field) or by specific items (the `item_id` field). Use the optional `search_options` parameter to control how videos are matched (by visual content, audio, or both). If you omit it, videos are matched on their visual content. Images are always matched on their visual content. 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. <Note title="Note"> This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. </Note>

Authentication

x-api-keystring
Your API key. <Note title="Note"> You can find your API key on the <a href="https://playground.twelvelabs.io/dashboard/api-keys" target="_blank">API Keys</a> page. </Note>

Path parameters

knowledge_store_idstringRequired
The unique identifier of the knowledge store.

Request

Request body for searching a knowledge store.

To paginate, set the page_token parameter to the next_page_token field returned in the previous response and send the request again. The token identifies the original search, so any search fields you send are ignored.

queryobjectRequired
The search query.
filterobjectOptional

Narrows results to specific items in the knowledge store.

Filter by type of item (the asset_type field) or by specific identifiers (the item_id field). Use eq to match a single value or in to match any value in a list. When you specify multiple fields, the platform applies all conditions together.

Examples:

1{
2    "asset_type": {
3        "eq": "video"
4    }
5}
1{
2    "asset_type": {
3        "in": [
4            "video"
5        ]
6    },
7    "item_id": {
8        "in": [
9            "ksi_069e9870-3c4d-7abc-9012-3456789abcde"
10        ]
11    }
12}

Omit the filter to search all items.

search_optionsobjectOptional

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. Providing options in the search_options.video field when the filter.asset_type field excludes videos returns a 400 error.

If you omit this field, videos are matched on their visual content.

group_byenumOptionalDefaults to 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.

page_sizeintegerOptional1-50Defaults to 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_tokenstringOptional

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.

A malformed or unrecognized token returns a 400 error. A token that has expired returns a 410 error (make a new search request to obtain a fresh page token).

include_metadatabooleanOptionalDefaults to false

Set to true to include metadata in each result. Each result includes a metadata object with a system field (platform-derived file properties such as duration and resolution) and a user field (metadata you attached to the item).

Response headers

X-Ratelimit-Limitdouble

The maximum number of requests you can make per rate limit window for this endpoint. For details, see the Rate limits page.

X-Ratelimit-Remainingdouble
The number of requests remaining in the current rate limit window for the specific endpoint.
X-Ratelimit-Useddouble
The number of requests you have made in the current rate limit window for the specific endpoint.
X-Ratelimit-Resetdouble
The time at which the current rate limit window resets, expressed in UTC epoch seconds.

Response

The search completed successfully.
datalist of objects
Search results, ordered by relevance.
effective_search_optionsobject

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_tokenstring

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
404
Not Found Error
410
Gone Error
429
Too Many Requests Error