Results, Evidence, and Returned Fields

Moment-returning APIs provide timestamped Shot objects for the matching parts of a video. Each Shot identifies the source video and exact time range, so an application can inspect the evidence, play an individual moment, or combine several results into one stream. Use return_fields to include the stored index rows associated with each result.

Search request
      ↓
Timestamped Shot
      ├── source video and time range
      ├── relevance score and matched text
      ├── hydrated index evidence
      └── playable stream

Result layer	What it provides
Identity	`video_id` and `video_title` identify the source.
Time	`start` and `end` locate the exact moment.
Relevance	`search_score` and optional text explain the match strength and content.
Evidence	`metadata["indexes"]` contains requested index rows.
Playback	`stream_url`, `player_url`, or `generate_stream()` makes the moment playable.

Basic result

response = video.search(
    query="find moments where a red car drives away",
)

for shot in response:
    print(shot.start, shot.end, shot.search_score)
    print(shot.generate_stream())

A Shot includes:

Field	Type	Description
`video_id`	string	Source video ID.
`video_length`	float	Source video duration in seconds.
`video_title`	string	Source video title.
`start`	float	Start time in seconds.
`end`	float	End time in seconds.
`text`	string or `None`	Optional matched text-like value.
`search_score`	float	Relevance score, when applicable.
`scene_index_id`	string or `None`	Index ID associated with the match, when available.
`scene_index_name`	string or `None`	Index name associated with the match, when available.
`metadata`	dict or `None`	Result metadata plus hydrated rows under `metadata["indexes"]`.
`stream_url`	string or `None`	Playable stream URL for this shot when already generated.
`player_url`	string or `None`	Player URL for this shot when already generated.

Example:

Shot(
    video_id="m-123",
    video_length=120.5,
    video_title="Store walkthrough",
    start=3.42,
    end=7.10,
    text="Just grabbing my Nike bag...",
    search_score=0.87,
    scene_index_id="idx-123",
    scene_index_name="scene",
    metadata={
        "indexes": {
            "objects": [
                {"label": "person", "count": 1, "max_score": 0.93},
                {"label": "cell phone", "count": 1, "max_score": 0.91},
            ]
        }
    },
    stream_url="https://stream.videodb.io/v3/published/manifests/result.m3u8",
    player_url="https://console.videodb.io/player/...",
)

APIs that return shots

These APIs return Shot objects:

# High-level v2 search: returns SearchResponse
response = video.search(query="happy reunion")
shots = response.shots

# Direct semantic search: returns SearchResult
semantic_results = video.semantic_search(query="happy reunion", index_names=["scene"])
shots = semantic_results.get_shots()

# Structured query: returns SearchResult
query_results = video.query(
    index_name="objects",
    filter=[{"field": "label", "op": "contains", "value": "cell phone"}],
    limit=100,
)
shots = query_results.get_shots()

aggregate() does not return shots; it returns aggregate rows. ask() returns an answer plus optional source shots.

Play a result

You can play an individual shot:

response.shots[0].play()

Or use the URL directly when present:

url = response.shots[0].stream_url

If a stream URL is not already present, generate it from the shot timestamps:

url = response.shots[0].generate_stream()

Return hydrated index rows

return_fields selects which indexes to hydrate for each matched scene. Hydrated rows are available in shot.metadata["indexes"], not shot.fields. For a single index:

results = video.semantic_search(
    query="person holding a phone",
    index_names=["scene"],
    top_k=10,
    return_fields=["scene"],
)

for shot in results:
    scene_rows = shot.metadata.get("indexes", {}).get("scene", [])
    print(scene_rows)

For high-level search across multiple indexes:

response = collection.search(
    query="person holding a phone",
    top_k=10,
    mode="default",
    return_fields=["scene", "objects"],
)

for shot in response:
    indexes = shot.metadata.get("indexes", {})
    print(indexes.get("scene", []))
    print(indexes.get("objects", []))

A hydrated Shot then looks like:

Shot(
    video_id="m-123",
    video_length=120.5,
    video_title="Store walkthrough",
    start=3.42,
    end=7.10,
    text="A person holds a phone while speaking.",
    search_score=0.91,
    scene_index_id="idx_scene_123",
    scene_index_name="scene",
    metadata={
        "indexes": {
            "scene": [
                {"scene_description": "A person holds a phone while speaking."}
            ],
            "objects": [
                {"label": "person", "count": 1, "max_score": 0.93},
                {"label": "cell phone", "count": 1, "max_score": 0.91},
            ],
        }
    },
    stream_url="https://stream.videodb.io/...",
    player_url="https://console.videodb.io/player/...",
)

For debugging, request all stored index rows for each matched scene:

response = video.search(
    query="product demo moments",
    top_k=10,
    return_fields="all",
)

Accepted return_fields values:

Value	Meaning
`None`	No additional hydration.
`"all"` or `"*"`	Hydrate all available indexes for the matched scene.
string	Hydrate one index by name or ID.
list	Hydrate selected indexes by name or ID.
dict	Dict keys select indexes; values are accepted for compatibility but are not field projections.

return_fields currently selects indexes, not individual fields. A hydrated index value is a list because one scene can map to multiple rows, such as several object labels or brand mentions.

Compile many results into one stream

For semantic_search() or query() results, compile the SearchResult directly:

results = video.semantic_search(query="product demo", index_names=["scene"])
stream_url = results.compile()

For high-level search(), compile the nested SearchResult:

response = video.search(query="product demo")
stream_url = response.results.compile()

Or build a stream from Shot timestamps:

timestamps = [(shot.start, shot.end) for shot in response]
stream_url = video.generate_stream(timestamps)

Generated streams are playable HLS URLs.

https://stream.videodb.io/v3/published/manifests/{manifest-id}.m3u8

Ask sources

ask() returns an answer and, when include_sources=True, supporting Shot objects.

answer = collection.ask(
    question="Which brands are mentioned?",
    include_sources=True,
)

print(answer.answer)

for source in answer.sources:
    print(source.video_id, source.start, source.end)
    print(source.generate_stream())

Result controls

Option	Type	Default	Description
`return_fields`	string, list, dict, or `"all"`	none	Select indexes to hydrate under `shot.metadata["indexes"]`.
`top_k`	int	API-specific	Maximum returned moments for search-style APIs.
`score_threshold`	float	none	Minimum semantic score for `semantic_search()`.
`limit`	int	API-specific	Maximum rows for `query()` and `aggregate()`.

Hydrated index rows can make responses larger. Keep return_fields narrow for broad search previews and use "all" mainly for debugging or final inspection.

Start Here

Core Concepts

Ingest

Understand

Act

Automate

Open Source Frameworks

Results, Evidence, and Returned Fields

Basic result

APIs that return shots

Play a result

Return hydrated index rows

Compile many results into one stream

Ask sources

Result controls

Next steps

Search APIs

Hybrid and Collection Search

​Basic result

​APIs that return shots

​Play a result

​Return hydrated index rows

​Compile many results into one stream

​Ask sources

​Result controls

​Next steps

Search APIs

Hybrid and Collection Search

Basic result

APIs that return shots

Play a result

Return hydrated index rows

Compile many results into one stream

Ask sources

Result controls

Next steps