> 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. ## Exclude items and filter custom metadata by range in knowledge store search Knowledge store search accepts `item_id.nin` to exclude every clip or image belonging to 1 to 20,000 listed items. You can use it on its own or with either `item_id.eq` or `item_id.in`. An item listed in `nin` is excluded even when `eq` or `in` selects it. The `user_metadata` filter also accepts inclusive `gte` and `lte` bounds on numbers and RFC 3339 timestamps with a timezone. You can use one or both bounds. Every metadata key you specify must match. These ranges apply to custom metadata you stored on the source asset or the knowledge store item. For searches without a `tags` filter, the combined 10,000-item limit still applies when you use metadata, enrichment, creation time, or location filters, including item inclusions and exclusions. A broader combined match returns `422 metadata_filter_too_broad`. For details, see the [Search a knowledge store](/v1.3/api-reference/knowledge-store-search/search) API reference and the SDK reference for [Python](/v1.3/sdk-reference/python/search-knowledge-store) and [Node.js](/v1.3/sdk-reference/node-js/search-knowledge-store). ## The new billing starts on October 15 The new billing starts on October 15, 2026. It replaces the separate Free plan, Developer plan, and Jockey subscriptions with one set of plans: Free, Plus, Pro, and Enterprise. Each plan includes a Managed Intelligence allowance and a monthly Workload allowance. Managed Intelligence is the service that stores your assets and keeps them ready to use. It includes processing and updates to the latest models. A Workload is a task that you run on your assets. Examples are creating Jockey responses, analyzing, segmenting, and embedding. New users start in the new billing. Existing users move in phases, and the date depends on your plan. Legacy billing applies to your plan until it moves. ### Actions required * **Developer plan users without a paid Jockey subscription**: Choose Plus or Pro before January 4, 2027. If you do not choose, you move to the Free plan on January 4, 2027. * **Jockey subscribers**: No action is needed to move. Your plan moves to the matching plan, Plus or Pro. A monthly subscription moves on your first billing date in January 2027. An annual subscription moves at the end of its term. * **Free plan users**: No action is needed to move. You move to the Free plan of the new billing on January 4, 2027. After your plan moves, every plan has one more action if you have pre-migration assets. Assets that you uploaded before your plan moved are pre-migration assets. To add a pre-migration asset to an index with Marengo enabled, or to a knowledge store, enable storage accounting for the asset first. Storage accounting makes the asset count toward the Managed Intelligence allowance of your plan. If you do not enable it, these requests return a `409` error. See [Enable storage accounting](/v1.3/docs/get-started/plans-and-billing/pre-migration-assets#enable-storage-accounting). For more information, see the following pages: * [Migrate to the new billing](/v1.3/docs/get-started/plans-and-billing/migrate-to-new-billing): When your plan moves. * [Plans, allowances, and overage](/v1.3/docs/get-started/plans-and-billing/plans-allowances-and-overage): How the new billing works. * [Rate limits](/v1.3/docs/get-started/plans-and-billing/rate-limits): The rate limits of each billing system. ## Introducing item tags Video items in a knowledge store now accept tags. A tag marks a moment or a range of the video and carries custom metadata as key-value pairs. A video item holds up to 100 tags. To use this feature, upgrade to the latest version of the Python or Node.js SDK: **`Python SDK`** ```sh Python SDK pip install --upgrade twelvelabs ``` **`Node.js SDK`** ```sh Node.js SDK npm install twelvelabs-js@latest ``` For details, see the [Create an item tag](/v1.3/api-reference/knowledge-store-items/item-tags/create) page in the API Reference section, or the SDK reference for [Python](/v1.3/sdk-reference/python/knowledge-store-items#create-an-item-tag) and [Node.js](/v1.3/sdk-reference/node-js/knowledge-store-items#create-an-item-tag). ## Introducing tag filtering for knowledge store search Knowledge store search now accepts a `tags` filter. The search returns only the clips within the moments and ranges that matching tags mark on video items. A tag matches when its `tag_metadata` field matches the metadata you specify. To use this feature, upgrade to the latest version of the Python or Node.js SDK: **`Python SDK`** ```sh Python SDK pip install --upgrade twelvelabs ``` **`Node.js SDK`** ```sh Node.js SDK npm install twelvelabs-js@latest ``` For details, see the [Search a knowledge store](/v1.3/api-reference/knowledge-store-search/search) page in the API Reference section, or the SDK reference for [Python](/v1.3/sdk-reference/python/search-knowledge-store) and [Node.js](/v1.3/sdk-reference/node-js/search-knowledge-store). ## Jockey is now generally available Jockey is a unified agentic system that reasons across your videos and images. **What you can do** * Summarize all your videos and images: themes, subjects, patterns, and key statistics * Search your videos and images by describing what you want, and receive an explanation of each match * Organize and categorize your videos and images * Find and sequence moments into highlight reels For more use cases, see the [Recipes](/v1.3/agents/recipes) section. **Get started** To use Jockey, follow one of the quickstarts: * [Create a response](/v1.3/agents/get-started/quickstart/create-a-response): Upload videos and images, build a knowledge store, and generate an overview of your content. * [Search a knowledge store](/v1.3/agents/get-started/quickstart/search-a-knowledge-store): Upload videos and images, build a knowledge store, and search it with a natural-language query. ## Introducing custom metadata, enrichment, and creation time filters for knowledge store search Knowledge store search now accepts the following filters: * `user_metadata`: Narrows results by custom metadata. * `enrichment`: Narrows results by enrichment values. * `created_at`: Narrows results by the creation time of the item. If a search matches more than 10,000 items, the platform returns a `422` error with the `metadata_filter_too_broad` code. To use this feature, upgrade to the latest version of the Python or Node.js SDK: **`Python SDK`** ```sh Python SDK pip install --upgrade twelvelabs ``` **`Node.js SDK`** ```sh Node.js SDK npm install twelvelabs-js@latest ``` For details, see the [Search a knowledge store](/v1.3/api-reference/knowledge-store-search/search) page in the API Reference section, or the SDK reference for [Python](/v1.3/sdk-reference/python/search-knowledge-store) and [Node.js](/v1.3/sdk-reference/node-js/search-knowledge-store). ## Introducing item metadata in knowledge store search results Knowledge store search results now include the custom metadata of the knowledge store item. A knowledge store item has two sets of custom metadata: the custom metadata of the source asset and the custom metadata of the knowledge store item. The two sets are separate. The same key can have different values in each set. When you set the `include_metadata` parameter to `true`, the `metadata` object of each result has these fields: * `system`: System-generated metadata. * `user`: The custom metadata of the source asset. * `item`: The custom metadata of the knowledge store item. This field is absent when no item metadata has been set. To use this feature, upgrade to the latest version of the Python or Node.js SDK: **`Python SDK`** ```sh Python SDK pip install --upgrade twelvelabs ``` **`Node.js SDK`** ```sh Node.js SDK npm install twelvelabs-js@latest ``` For details, see the [Search a knowledge store](/v1.3/api-reference/knowledge-store-search/search) page in the API Reference section, or the SDK reference for [Python](/v1.3/sdk-reference/python/search-knowledge-store) and [Node.js](/v1.3/sdk-reference/node-js/search-knowledge-store). ## Billing amount replaces `usage` in the Jockey response The response of the Jockey Responses API no longer carries the `usage` field, which held the model input and output tokens. The response now carries `billing`: the cost of the response, as `billing.amount` in the currency `billing.currency`, which is `USD`. The amount counts everything the response ran, including model calls, searches, and tools, and it is the list price, before any discount on your account. Only a finished response carries `billing`, and `billing.amount` is `null` when the cost could not be determined at the time the response finished. Your invoice is the authoritative record of charges. If your code reads `response.usage`, read `response.billing.amount` instead. To use the new field, upgrade to the latest version of the Python or Node.js SDK: **`Python SDK`** ```sh Python SDK pip install --upgrade twelvelabs ``` **`Node.js SDK`** ```sh Node.js SDK npm install twelvelabs-js@latest ``` For details, see [The response object](/v1.3/api-reference/responses/the-response-object) page in the API Reference section.