Search

This guide shows you how to query indexed video with a natural-language search and read the ranked results.

Search is a pure-read POST operation. It uses SEARCH_CONTENT and ignores Idempotency-Key.

Query Indexed Evidence

curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/search" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "person entering through the north door",
    "video_ids": ["vid_0190b5d4-7e1f-7a2b-9c3d-1234567890ab"],
    "threshold": 0.82,
    "limit": 10
  }'

query is required. threshold defaults to 0.7 and accepts 0 through 1. limit defaults to 25 and accepts 1 through 100. If video_ids is present, every id must be visible to the key's workspace.

Result Shape

The response shape looks like the standard list envelope:

{
  "data": [
    {
      "id": "vid_0190b5d4_frame_0042",
      "video_id": "vid_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
      "title": "warehouse-inspection.mp4",
      "time_position": 222000,
      "score": 0.94,
      "tags": ["person", "north door"],
      "scene_description": "A person enters through the north door."
    }
  ],
  "next_cursor": null,
  "has_more": false
}

time_position is milliseconds from the start of the video. image and video_url, when present, are reviewable signed URLs. Do not treat score as evidence; use the timestamp and the returned media or scene description.

Search results are single-page: the request body has no cursor parameter, so next_cursor and has_more cannot be used to fetch another page. To see more or fewer results, adjust limit (max 100) or narrow the search with video_ids or threshold.

Empty And Stale Results

An empty data array is a valid result. Search can lag a recent indexing write. Wait for the video status to become completed before searching, and handle an empty page without converting it into a failure.