> This page is for version v1.3 (default).
> For other versions, use one of these documentation indexes:
> - v1.3 (default): https://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://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

> Quickstart: search video content. Working example with core search parameters.

This quickstart guide provides a simplified introduction to searching video content using the TwelveLabs Video Understanding Platform. It includes the following:

* A basic working example
* Minimal implementation details
* Core parameters for common use cases

For a comprehensive guide, see the [Search](/v1.3/docs/guides/search) page.

# Key concepts

This section explains the key concepts and terminology used in this guide:

* **Index**: A container that organizes your video content
* **Asset**: Your uploaded content. Once created, you can reference the same asset across multiple operations without uploading the file again.
* **Indexed asset**: An asset that has been indexed and is ready for downstream tasks.

# Workflow

Upload and index your videos before you search them. The platform indexes videos asynchronously. You can search your videos after indexing completes. Search results show video segments that match your search terms.

# Prerequisites

* To use the platform, you need an API key:

  If you don't have an account, [sign up](https://playground.twelvelabs.io/) for a free account.

  Go to the [API Keys](https://playground.twelvelabs.io/dashboard/api-keys) page.

  If you need to create a new key, select the **Create API Key** button. Enter a name and set the expiration period. The default is 12 months.

  Select the **Copy** icon next to your key to copy it to your clipboard.

* Depending on the programming language you are using, install the TwelveLabs SDK by entering one of the following commands:

  **`Python`**

  ```shell Python
  pip install --upgrade twelvelabs
  ```

  **`Node.js`**

  ```shell Node.js
  yarn add twelvelabs-js@latest # or npm install twelvelabs-js@latest
  ```

* Your videos must meet the following requirements:
  * **Upload limits**: Public video URLs up to 4 GB or local videos up to 200 MB. For local files up to 4 GB, see the [Upload and processing methods](/v1.3/docs/concepts/upload-methods) page.
  * **Model capabilities**: See the complete [requirements](/v1.3/docs/concepts/models/marengo/marengo-3-0#video-file-requirements) for resolution, aspect ratio, and supported formats.

# Starter code

Copy and paste the code below, replacing the placeholders surrounded by `<>` with your values.

**`Python`**

```Python Python maxLines=12
import time
from twelvelabs import TwelveLabs

# 1. Initialize the client
client = TwelveLabs(api_key="<YOUR_API_KEY>")

# 2. Create an index
# An index is a container for organizing your video content
index = client.indexes.create(
    index_name="<YOUR_INDEX_NAME>",
    models=[{"model_name": "marengo3.0", "model_options": ["visual", "audio"]}]
)
if not index.id:
    raise RuntimeError("Failed to create an index.")
print(f"Created index: id={index.id}")

# 3. Upload a video
asset = client.assets.create(
    method="url",
    url="<YOUR_VIDEO_URL>" # Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported.
    # Or use method="direct" and file=open("<PATH_TO_VIDEO_FILE>", "rb") to upload a local file up to 200 MB
)
print(f"Created asset: id={asset.id}")

# 4. Check the status of the asset
print("Waiting for asset to be ready...")
while True:
    asset = client.assets.retrieve(asset.id)
    if asset.status == "ready":
        print("Asset is ready")
        break
    if asset.status == "failed":
        raise RuntimeError(f"Asset processing failed: id={asset.id}")
    time.sleep(5)

# 5. Index your video
indexed_asset = client.indexes.indexed_assets.create(
    index_id=index.id,
    asset_id=asset.id
)
print(f"Created indexed asset: id={indexed_asset.id}")

# 6. Monitor the indexing process
print("Waiting for indexing to complete.")
while True:
    indexed_asset = client.indexes.indexed_assets.retrieve(
        index.id,
        indexed_asset.id
    )
    print(f"  Status={indexed_asset.status}")

    if indexed_asset.status == "ready":
        print("Indexing complete!")
        break
    elif indexed_asset.status == "failed":
        raise RuntimeError("Indexing failed")

    time.sleep(5)

# 7. Perform a search
search_results = client.search.query(
    index_id=index.id,
    query_text="<YOUR_QUERY>",
    search_options=["visual", "audio"]
)

# 8. Process the search results
print("\nSearch results:")
print("Each result shows a video clip that matches your query:\n")
for i, clip in enumerate(search_results):
    print(f"Result {i + 1}:")
    print(f"  Video ID: {clip.video_id}")  # Unique identifier of the video
    print(f"  Rank: {clip.rank}")  # Relevance ranking (1 = most relevant)
    print(f"  Time: {clip.start}s - {clip.end}s")  # When this moment occurs in the video
    print()
```

**`Node.js`**

```JavaScript Node.js maxLines=12
import { TwelveLabs } from "twelvelabs-js";
// Uncomment the next line if uploading a local file
// import fs from "fs";

// 1. Initialize the client
const client = new TwelveLabs({ apiKey: "<YOUR_API_KEY>" });

// 2. Create an index
// An index is a container for organizing your video content
const index = await client.indexes.create({
  indexName: "<YOUR_INDEX_NAME>",
  models: [{ modelName: "marengo3.0", modelOptions: ["visual", "audio"] }]
});
if (!index.id) {
  throw new Error("Failed to create an index.");
}
console.log(`Created index: id=${index.id}`);

// 3. Upload a video
const asset = await client.assets.create({
  method: "url",
  url: "<YOUR_VIDEO_URL>" // Use direct links to raw media files. Video hosting platforms and cloud storage sharing links are not supported
  // Or use method: "direct" and file: fs.createReadStream("<PATH_TO_VIDEO_FILE>") to upload a local file up to 200 MB
});
console.log(`Created asset: id=${asset.id}`);

// 4. Check the status of the asset
console.log("Waiting for asset to be ready...");
let readyAsset = await client.assets.retrieve(asset.id);
while (readyAsset.status !== "ready" && readyAsset.status !== "failed") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  readyAsset = await client.assets.retrieve(asset.id);
}
if (readyAsset.status === "failed") {
  throw new Error(`Asset processing failed: id=${asset.id}`);
}
console.log("Asset is ready");

// 5. Index your video
let indexedAsset = await client.indexes.indexedAssets.create(index.id, {
  assetId: asset.id
});
console.log(`Created indexed asset: id=${indexedAsset.id}`);

// 6. Monitor the indexing process
console.log("Waiting for indexing to complete.");
while (true) {
  indexedAsset = await client.indexes.indexedAssets.retrieve(
    index.id,
    indexedAsset.id
  );
  console.log(`  Status=${indexedAsset.status}`);

  if (indexedAsset.status === "ready") {
    console.log("Indexing complete!");
    break;
  } else if (indexedAsset.status === "failed") {
    throw new Error("Indexing failed");
  }

  await new Promise(resolve => setTimeout(resolve, 5000));
}

// 7. Perform a search request
const searchResults = await client.search.query({
  indexId: index.id,
  queryText: "<YOUR_QUERY>",
  searchOptions: ["visual", "audio"]
});

// 8. Process the search results
console.log("\nSearch results:");
console.log("Each result shows a video clip that matches your query:\n");
let resultIndex = 0;
for await (const clip of searchResults) {
  console.log(`Result ${++resultIndex}:`);
  console.log(`  Video ID: ${clip.videoId}`);  // Unique identifier of the video
  console.log(`  Rank: ${clip.rank}`);  // Relevance ranking (1 = most relevant)
  console.log(`  Time: ${clip.start}s - ${clip.end}s\n`);  // When this moment occurs in the video
}
```

# Code explanation

#### Import the SDK and initialize the client

Create a client instance to interact with the TwelveLabs Video Understanding Platform.

#### Create an index

Indexes store and organize your video data, allowing you to group related videos. Create one before uploading videos. See the [Indexes](/v1.3/docs/concepts/indexes) page for more details.

#### Upload a video

Upload a video file to create an asset.

#### Check the status of the asset

Asset processing is asynchronous. Poll the status of the asset until it is `ready` before you use it.

#### Index your video

Index your video by adding the asset created in the previous step to an index.

#### Monitor the indexing process

Monitor the status of the indexing process. Processing completes when the status changes to "ready".

#### Perform a search

Search your videos using natural language. The platform returns video segments that match your query.

#### Process the search results

Process and display the results. Each result includes the video ID, relevance ranking, and the time range where the match occurs.