Search a knowledge store

Narrows results to specific items in the knowledge store. Omit the filter to search all items.

You can filter with these fields:

• asset_type: The type of item. Use eq to match one type. Use in to match any type in a list.
• item_id: Specific items. Use eq to match one item. Use in to match any item in a list.
• user_metadata: Custom metadata. Map each key to the eq operator to match one value, or to the in operator to match any value in a list.
• enrichment: Enrichment values that the platform extracts. Map each key to the eq operator to match one value, or to the in operator to match any value in a list.
• created_at: Creation time. Use gte to set the earliest time and lte to set the latest time. You can use one or both.
• location: Capture location. Provide the center and the radius of a circle.
• tags: Item tags. Map each key under tags.metadata to the eq operator to match one value, or to the in operator to match any value in a list.

An item must match all of the fields that you specify. The tags field also limits which clips of an item the search returns.

When you use any of the user_metadata, enrichment, created_at, or location fields, the platform counts the items that match those conditions together. If more than 10,000 items match, the platform returns a 422 error with the metadata_filter_too_broad code. To reduce the count, add conditions or use the item_id field. The asset_type field does not reduce the count. When you use the tags field, the platform does not count items, and this limit does not apply. It counts the matching tags instead, as the tags field describes.

Examples:

{
    "asset_type": {
        "eq": "video"
    }
}

{
    "asset_type": {
        "in": [
            "video"
        ]
    },
    "item_id": {
        "in": [
            "ksi_069e9870-3c4d-7abc-9012-3456789abcde"
        ]
    }
}

{
    "user_metadata": {
        "category": {
            "eq": "tutorial"
        }
    },
    "created_at": {
        "gte": "2026-09-01T00:00:00Z"
    }
}

{
    "location": {
        "latitude": 37.5665,
        "longitude": 126.978,
        "radius_meters": 5000
    }
}

{
    "tags": {
        "metadata": {
            "event": {
                "eq": "goal"
            }
        }
    }
}

Specifies how videos are matched. Videos are the only type of item with configurable options, set in the search_options.video field. Images are always matched on their visual content and have no options to configure.

To choose which types of items to search, use the filter.asset_type field. If you provide options in the search_options.video field when the filter.asset_type field excludes videos, the platform returns a 400 error.

If you omit this field, videos are matched on their visual content.

Controls how the platform groups matches in the response.

• none: Returns individual matches ordered by relevance.
• item: Groups matches under their parent item.

Default: none.

The maximum number of results per page. A result is one entry in the data array. With the group_by parameter set to its default of none, each result is an individual match: a video clip or an image. When set to item, each result is one item: a video with all its matching clips, or an image.

Default: 10. Max: 50.

Pagination token used to retrieve the next page of results. Omit it on the first request. To fetch the next page, set it to the next_page_token field returned in the previous response and send the request again.

If a token is malformed or unrecognized, the platform returns a 400 error. If a token has expired, the platform returns a 410 error (make a new search request to obtain a fresh page token).

Set to true to include metadata in each result. Each result includes a metadata object with these fields:

• system: System-generated metadata, such as duration and resolution.
• user: The custom metadata of the source asset.
• item: The custom metadata of the knowledge store item.