Learn
How can I find a specific person in a video?
You find a specific person in a video by registering them as an entity with reference images, then adding that entity to a search run against an index with Marengo enabled. We return candidate video segments where the person appears, so an editor can move from a name to a clip with far less manual scanning of footage.

TwelveLabs
Learn
How can I find a specific person in a video?
You find a specific person in a video by registering them as an entity with reference images, then adding that entity to a search run against an index with Marengo enabled. We return candidate video segments where the person appears, so an editor can move from a name to a clip with far less manual scanning of footage.

TwelveLabs


Nov 10, 2026
8 minutes
Copy link to article
You find a specific person in a video by registering them as an entity with reference images, then adding that entity to a search run against an index with Marengo enabled. We return candidate video segments where the person appears, so an editor can move from a name to a clip with far less manual scanning of footage. Match accuracy, including for look-alikes, still needs to be tested on the archive being searched.
We offer four routes: entity search, image or composed queries, text queries (our documented example is a famous person), and Pegasus image-guided analysis. Entity search matches registered reference images grouped in a collection. An image or composed query matches visual resemblance to a photo, with no registration. Pegasus takes reference images in the prompt and works on a video from a URL or an asset without pre-indexing. In our experience, entity search works best for repeat lookups of the same person, while an image or composed query is the faster pick for a one-off check.
Key Takeaways
Registering a person as an entity with reference images and adding it to a search query returns the segments where that person appears.
Entity search uses registered reference images, and our entity search docs say that grouping related entities in a collection improves accuracy and helps management.
An image or composed query finds visually similar content from one photo, with no setup and no registered identity.
Our take, not an official rule: use entity search for repeat lookups of one person, and an image query for a one-off check.
Five or more reference images for each entity is our accuracy recommendation.
Focused collections of related entities, such as one for each roster or production, support accuracy.
Entity Search runs on an index with Marengo enabled for search.
Face-based identification of real people calls for a consent and acceptable use check before a pilot starts.
Limits of Filename and Transcript Search for Finding a Person
Filename and tag search is limited to what an annotator wrote down in advance. If no one tagged a person in a clip, a keyword query returns nothing for that clip, and complete tagging is unrealistic on a large archive. Archives that need to make a video library searchable face this limit whenever annotators have not tagged every person.
Transcript-only search has a different limit. A scene defined by visual presence has no matching words when the person on screen says nothing, and a spoken name may refer to someone who is not in the frame.
Semantic video search matches meaning across visuals, audio, and speech, which gives a person query more signals than a transcript can supply. Our Marengo docs include an example that pairs visual recognition of a famous person with speech in a single semantic query.
Ways to Find a Person
Entity Search for Repeat Lookups
An entity represents a specific person. Assets are the reference images that define the entity, and an entity collection is a group of entities. These records work with entity search to identify and locate that person across an index.
Our entity search docs list sports highlights, movie character screen time, and security footage as use cases. Several reference images per person should help identification across variations in lighting conditions and camera angles.
Image and Composed Queries for One-Off Lookups
Our search guide covers text, image, and composed queries. A single photo can drive a query, and our Search product page describes how an editor can find a player from a single photo. A composed query adds a sentence to the photo, so an image plus a sentence in one query can narrow results to a person in a particular situation. Composed queries run through the search endpoint use Marengo.
The search guide defines an image query as finding visually similar content. An image query matches visual resemblance to the photo and has no link to a registered identity. Entity search instead matches against registered reference images.
Text Queries and Famous People
A plain text query is a third route. The documented example is a famous person, in one Playground example that combines visuals and speech. That example is not a coverage guarantee, and our documentation does not define how well text queries work for other people, so a pilot should test the intended subjects before relying on it. For specific people such as employees and players, entity registration is the documented path, and a text name alone should not be assumed to identify a private individual.
Pegasus Image-Guided Analysis for a Single Video
A fourth route fits a question about one video. Pegasus takes reference images in the prompt and returns timestamps for a video analyzed from a URL or an asset, with no pre-indexing. For an ad hoc question about a single video, that avoids building an index and an entity collection first.
Length matters for this route. Pegasus handles up to 2 hours of video, or up to 4 hours when analyzing only a portion of it. A shared 261,120-token window covers the input, the output, and the reference images. A long-form broadcast or sports asset may therefore not fit in one pass, so check the asset length first.
Pegasus image-guided analysis has no documented registration step that would keep an identity for repeat lookups. A pilot should test the route on the intended footage and confirm whether it fits repeated use.
Setting Up Entity Search
Prerequisites
Setup needs an index with uploaded videos and Marengo enabled for search, plus basic familiarity with search requests. Our quickstart shows how to index a video and run a first search. It covers creating a search index and running a search with visual and audio options.
Upload limits apply to the videos in that index. At the time of writing, our upload methods docs list public video URLs up to 4 GB and local videos up to 200 MB by the default upload method. Larger local files use multipart upload, so they do not need to be hosted publicly. Check that page before planning around a size.
Create a Collection and Add Entities
The API flow has three steps:
Create the entity collection.
Upload each reference image as an asset.
Create the entity from the uploaded assets.
The same work can be done without writing code in our Playground. The flow starts with Entities in the sidebar, then Create Entity Collection, then entering the entity name and uploading images.
Clear reference images with varied angles and lighting should improve matches, and different outfits add more variation to match against. Our entity search docs call for at least five images in the Playground, and the API accepts one asset. Five or more is our accuracy recommendation.
Check the current image format and size requirements in our entity search docs before a bulk upload. Those limits differ across pages, and a reference image that falls outside them can be rejected at upload.
Run the Search
In the Playground, an editor adds an entity to the search with the Add Entity button. In the API, the entity's unique identifier goes in the query text between <@ and > markers, for example <@entity123> is walking. Each request targets one index and cannot span several.
Building on several indexes therefore means running the query against each index separately and combining the segment lists in application code.
Organizing Collections for Accuracy
Collections work best when each one holds related people. Our entity search docs say that grouping related entities improves accuracy and helps with management. The example there is a collection for the players on a soccer team.
The same approach works with one collection for each roster or production. Keeping unrelated groups in separate collections makes them easier to manage. Because the free plan allows one collection and the sample collection may use that slot, a multi-collection layout needs a plan with higher limits. Confirm the plan name and limits in our current pricing details and in our entity search docs.
What to Verify in a Pilot
A pilot should measure time-to-clip for a specific person against the current manual process, using a representative slice of the archive. The same test should include people who look alike, so the pilot can show whether grouping related entities in one collection improves how well similar faces are separated.
Several checks belong on the pilot list:
Confirm consent, legal basis, and acceptable use for face-based identification before enrolling reference images of real people.
Compare results from one reference image against five or more. The API accepts one image, while the Playground guidance calls for at least five.
Test footage with varied lighting and camera angles.
Confirm the index uses Marengo for search.
Check collection and entity counts against current plan limits.
Confirm at setup whether the sample collection can be reused or removed, since it may use the free plan's one collection slot.
Plan how segment lists from separate indexes will be combined.
If using Pegasus for a single video, check the asset length and the token budget for reference images.
FAQs
Can a Person Be Found Without Setting Up an Entity?
Yes, in some cases. A single photo can drive an image query, which finds visually similar content rather than a registered identity. A composed query adds a sentence to narrow the results to a particular situation. The documented famous-person query example is not a coverage guarantee, so a pilot should test the intended subjects. Entity registration is the documented path for specific people such as employees and players.
How Many Reference Images Does an Entity Need?
Five or more clear images is our accuracy recommendation, with varied angles and lighting so the entity has more to match against across different footage. The Playground guidance calls for at least five images, and the API minimum is one asset.
Can One Search Cover Several Indexes?
No. Each search request targets one index and cannot span several. Building on several indexes means running the query against each one and combining the segment lists in application code.
Does Entity Search Work With Marengo Embeddings?
Not through the /search endpoint, which does not query the embeddings model. Search and entity search need an index with Marengo enabled for search, and those embeddings are not compatible with the embeddings behind platform search.
What Does the Free Plan Allow for Entity Search?
As of this writing, the free plan includes one entity collection with up to fifteen entities in total, and the default sample collection counts toward that limit. More collections require a plan with higher limits. Confirm the current plan details before planning around them.
See a Demo
We can walk through person search on a representative video library, including how collection layout and index choice affect results. See a demo.
You find a specific person in a video by registering them as an entity with reference images, then adding that entity to a search run against an index with Marengo enabled. We return candidate video segments where the person appears, so an editor can move from a name to a clip with far less manual scanning of footage. Match accuracy, including for look-alikes, still needs to be tested on the archive being searched.
We offer four routes: entity search, image or composed queries, text queries (our documented example is a famous person), and Pegasus image-guided analysis. Entity search matches registered reference images grouped in a collection. An image or composed query matches visual resemblance to a photo, with no registration. Pegasus takes reference images in the prompt and works on a video from a URL or an asset without pre-indexing. In our experience, entity search works best for repeat lookups of the same person, while an image or composed query is the faster pick for a one-off check.
Key Takeaways
Registering a person as an entity with reference images and adding it to a search query returns the segments where that person appears.
Entity search uses registered reference images, and our entity search docs say that grouping related entities in a collection improves accuracy and helps management.
An image or composed query finds visually similar content from one photo, with no setup and no registered identity.
Our take, not an official rule: use entity search for repeat lookups of one person, and an image query for a one-off check.
Five or more reference images for each entity is our accuracy recommendation.
Focused collections of related entities, such as one for each roster or production, support accuracy.
Entity Search runs on an index with Marengo enabled for search.
Face-based identification of real people calls for a consent and acceptable use check before a pilot starts.
Limits of Filename and Transcript Search for Finding a Person
Filename and tag search is limited to what an annotator wrote down in advance. If no one tagged a person in a clip, a keyword query returns nothing for that clip, and complete tagging is unrealistic on a large archive. Archives that need to make a video library searchable face this limit whenever annotators have not tagged every person.
Transcript-only search has a different limit. A scene defined by visual presence has no matching words when the person on screen says nothing, and a spoken name may refer to someone who is not in the frame.
Semantic video search matches meaning across visuals, audio, and speech, which gives a person query more signals than a transcript can supply. Our Marengo docs include an example that pairs visual recognition of a famous person with speech in a single semantic query.
Ways to Find a Person
Entity Search for Repeat Lookups
An entity represents a specific person. Assets are the reference images that define the entity, and an entity collection is a group of entities. These records work with entity search to identify and locate that person across an index.
Our entity search docs list sports highlights, movie character screen time, and security footage as use cases. Several reference images per person should help identification across variations in lighting conditions and camera angles.
Image and Composed Queries for One-Off Lookups
Our search guide covers text, image, and composed queries. A single photo can drive a query, and our Search product page describes how an editor can find a player from a single photo. A composed query adds a sentence to the photo, so an image plus a sentence in one query can narrow results to a person in a particular situation. Composed queries run through the search endpoint use Marengo.
The search guide defines an image query as finding visually similar content. An image query matches visual resemblance to the photo and has no link to a registered identity. Entity search instead matches against registered reference images.
Text Queries and Famous People
A plain text query is a third route. The documented example is a famous person, in one Playground example that combines visuals and speech. That example is not a coverage guarantee, and our documentation does not define how well text queries work for other people, so a pilot should test the intended subjects before relying on it. For specific people such as employees and players, entity registration is the documented path, and a text name alone should not be assumed to identify a private individual.
Pegasus Image-Guided Analysis for a Single Video
A fourth route fits a question about one video. Pegasus takes reference images in the prompt and returns timestamps for a video analyzed from a URL or an asset, with no pre-indexing. For an ad hoc question about a single video, that avoids building an index and an entity collection first.
Length matters for this route. Pegasus handles up to 2 hours of video, or up to 4 hours when analyzing only a portion of it. A shared 261,120-token window covers the input, the output, and the reference images. A long-form broadcast or sports asset may therefore not fit in one pass, so check the asset length first.
Pegasus image-guided analysis has no documented registration step that would keep an identity for repeat lookups. A pilot should test the route on the intended footage and confirm whether it fits repeated use.
Setting Up Entity Search
Prerequisites
Setup needs an index with uploaded videos and Marengo enabled for search, plus basic familiarity with search requests. Our quickstart shows how to index a video and run a first search. It covers creating a search index and running a search with visual and audio options.
Upload limits apply to the videos in that index. At the time of writing, our upload methods docs list public video URLs up to 4 GB and local videos up to 200 MB by the default upload method. Larger local files use multipart upload, so they do not need to be hosted publicly. Check that page before planning around a size.
Create a Collection and Add Entities
The API flow has three steps:
Create the entity collection.
Upload each reference image as an asset.
Create the entity from the uploaded assets.
The same work can be done without writing code in our Playground. The flow starts with Entities in the sidebar, then Create Entity Collection, then entering the entity name and uploading images.
Clear reference images with varied angles and lighting should improve matches, and different outfits add more variation to match against. Our entity search docs call for at least five images in the Playground, and the API accepts one asset. Five or more is our accuracy recommendation.
Check the current image format and size requirements in our entity search docs before a bulk upload. Those limits differ across pages, and a reference image that falls outside them can be rejected at upload.
Run the Search
In the Playground, an editor adds an entity to the search with the Add Entity button. In the API, the entity's unique identifier goes in the query text between <@ and > markers, for example <@entity123> is walking. Each request targets one index and cannot span several.
Building on several indexes therefore means running the query against each index separately and combining the segment lists in application code.
Organizing Collections for Accuracy
Collections work best when each one holds related people. Our entity search docs say that grouping related entities improves accuracy and helps with management. The example there is a collection for the players on a soccer team.
The same approach works with one collection for each roster or production. Keeping unrelated groups in separate collections makes them easier to manage. Because the free plan allows one collection and the sample collection may use that slot, a multi-collection layout needs a plan with higher limits. Confirm the plan name and limits in our current pricing details and in our entity search docs.
What to Verify in a Pilot
A pilot should measure time-to-clip for a specific person against the current manual process, using a representative slice of the archive. The same test should include people who look alike, so the pilot can show whether grouping related entities in one collection improves how well similar faces are separated.
Several checks belong on the pilot list:
Confirm consent, legal basis, and acceptable use for face-based identification before enrolling reference images of real people.
Compare results from one reference image against five or more. The API accepts one image, while the Playground guidance calls for at least five.
Test footage with varied lighting and camera angles.
Confirm the index uses Marengo for search.
Check collection and entity counts against current plan limits.
Confirm at setup whether the sample collection can be reused or removed, since it may use the free plan's one collection slot.
Plan how segment lists from separate indexes will be combined.
If using Pegasus for a single video, check the asset length and the token budget for reference images.
FAQs
Can a Person Be Found Without Setting Up an Entity?
Yes, in some cases. A single photo can drive an image query, which finds visually similar content rather than a registered identity. A composed query adds a sentence to narrow the results to a particular situation. The documented famous-person query example is not a coverage guarantee, so a pilot should test the intended subjects. Entity registration is the documented path for specific people such as employees and players.
How Many Reference Images Does an Entity Need?
Five or more clear images is our accuracy recommendation, with varied angles and lighting so the entity has more to match against across different footage. The Playground guidance calls for at least five images, and the API minimum is one asset.
Can One Search Cover Several Indexes?
No. Each search request targets one index and cannot span several. Building on several indexes means running the query against each one and combining the segment lists in application code.
Does Entity Search Work With Marengo Embeddings?
Not through the /search endpoint, which does not query the embeddings model. Search and entity search need an index with Marengo enabled for search, and those embeddings are not compatible with the embeddings behind platform search.
What Does the Free Plan Allow for Entity Search?
As of this writing, the free plan includes one entity collection with up to fifteen entities in total, and the default sample collection counts toward that limit. More collections require a plan with higher limits. Confirm the current plan details before planning around them.
See a Demo
We can walk through person search on a representative video library, including how collection layout and index choice affect results. See a demo.
Enterprise
©
2026
TwelveLabs, Inc. All Rights Reserved
Enterprise
©
2026
TwelveLabs, Inc. All Rights Reserved
Enterprise
©
2026
TwelveLabs, Inc. All Rights Reserved





