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

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.

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

Reference: https://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. 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: ```json { "asset_type": { "eq": "video" } } ``` ```json { "asset_type": { "in": [ "video" ] }, "item_id": { "in": [ "ksi_069e9870-3c4d-7abc-9012-3456789abcde" ] } } ``` Omit the filter to search all items.
- `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 a `system` field (platform-derived file properties such as duration and resolution) and a `user` field (metadata you attached to the 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 specified resource does not exist.

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

### 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. 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: ```json { "asset_type": { "eq": "video" } } ``` ```json { "asset_type": { "in": [ "video" ] }, "item_id": { "in": [ "ksi_069e9870-3c4d-7abc-9012-3456789abcde" ] } } ``` Omit the filter to search all items.

- `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. Provide exactly one operator: `eq` to match one item, or `in` to match any of the listed items.

### 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 whose `asset_type` equals this value.
  - Allowed values: `video`, `image`
- `in` (list of enum, optional) — Match items whose `asset_type` is one of these values.
  - Allowed values: `video`, `image`

### ItemIdFilter

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

- `eq` (string, optional) — Match the item with this identifier.
- `in` (list of string, optional) — Match any item whose identifier is in this list.

### 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 media metadata for the source video.
- `user` (map from string to KnowledgeStoreMetadataValue, optional) — Caller-supplied key-value pairs attached to the item.

### ImageSearchItemMetadata

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

- `system` (ImageSearchSystemMetadata, optional) — System-generated media metadata for the source image.
- `user` (map from string to KnowledgeStoreMetadataValue, optional) — Caller-supplied key-value pairs attached to the item.

### VideoSearchSystemMetadata

System-generated media 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` (integer, 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.

### ImageSearchSystemMetadata

System-generated media 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` (integer, 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()
```

### 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()
```