This guide helps you evaluate which Video Understanding workflows should be migrated to the Video agents (Jockey) and provides a step-by-step process for migrating a search workflow.

Choose the workflows to migrate

Some workflows can move to the Video agents (Jockey). Others should continue using the existing Video Understanding APIs.

Current workflow	Recommendation	Reason
Search for moments in videos	Evaluate migration to the Responses API.	The Video agents (Jockey) adds cross-video reasoning, multi-turn refinement, and structured output to search workflows.
Analyze a single video for summaries or Q&A	Keep using the Analyze API.	The Analyze API is designed for stateless, single-video analysis. The Video agents (Jockey) is built for collections. If your workflow needs reasoning across multiple videos, consider the Responses API instead.
Generate embeddings for machine-learning pipelines	Keep using the Embed API.	The Video agents (Jockey) does not generate vector embeddings.

Compare concepts

Video Understanding	Video agents (Jockey)	Difference
Index	Knowledge store	A knowledge store holds your videos plus derived understanding - entities, relationships, and embeddings - not just a vector index.
Indexed video	Asset + knowledge store item	Upload creates an asset. Adding it to a knowledge store creates an item. One asset can exist in multiple knowledge stores.
Marengo / Pegasus	Jockey	No model selection needed. Jockey is a unified model that handles all modalities automatically.
`POST /search`	`POST /responses`	Natural language replaces structured search parameters.
Search options (visual, conversation, text_in_video)	Automatic	Jockey reasons across all modalities without explicit configuration.
`POST /embed`	No equivalent	Continue using the Embed API for vector embeddings.

Migrate a search workflow

This example shows how to move a Video Understanding search workflow to Video agents (Jockey). Both approaches start by uploading a video as an asset. The differences begin after upload.

Step	Video Understanding	Video agents (Jockey)
1. Upload an asset	Upload a video file or URL	Same
2. Create a container	Create an index with engine and modality config	Create a knowledge store - no engine config needed
3. Add the asset	Add to index, poll until indexed	Add to knowledge store, poll until indexed
4. Query	`POST /search` with structured parameters	`POST /responses` with natural language

What you gain:

No model or engine selection: Jockey handles all modalities automatically
Natural language queries: describe what you want instead of specifying search options
Follow-up queries: refine results in a multi-turn session
Corpus-level reasoning: generate responses that reason across your entire video collection
Structured output : Retrieve typed JSON responses using a schema

For a working code example of the Video agents (Jockey) workflow, see the Quickstart.

Recommended approach

If your team currently uses Video Understanding:

Keep Embed API workflows as-is. Video agents (Jockey) does not generate embeddings.
Keep stateless Analyze workflows as-is. Single-video, one-shot analysis stays on the Analyze API.
Evaluate search workflows for migration. If you need cross-video reasoning, multi-turn refinement, or structured search results, Video agents (Jockey) is the upgrade path.
Start with a pilot knowledge store. Upload a subset of your existing content and compare results side-by-side before migrating production search.

Private Beta limitations

During the Private Beta period:

Webhooks are not available. Use polling to check processing status
Rate limits may differ from Video Understanding
The API surface may change before general availability
SLAs do not apply

Video Understanding continues to operate. Adopt Video agents (Jockey) at your own pace.

Next steps

Guides - explore the capabilities of the platform.