Skip to main content
POST
Query a Collection

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id
string<uuid>
required

The ID of the Collection to query. All Inputs in the Collection must be uploaded and in a valid state for queries. Queries on a video Collection are disabled until each video in the Collection has completed it's background analysis pre-processing .

Body

application/json
question
string
required

The question to ask about the input content. Required if use_preset is false.

Maximum string length: 10000
query_type
enum<string>
default:synchronous

The type of the query. Synchronous queries block and return results in response. For video input collections, queries must use artifacts from the auto-triggered analyze inference job.

Available options:
synchronous,
asynchronous
use_preset
boolean
default:false

Private preview: Use custom context for synchronous queries. If set to true, the response populates structured_answer. Reach out to [email protected] to setup custom context and structured responses.

Response

Query processed successfully

id
string<uuid>
project_id
string<uuid>
input_id
string<uuid> | null
collection_id
string<uuid> | null
query_type
enum<string>
Available options:
asynchronous,
synchronous,
background
model
enum<string>

The perception model used for this query.

Available options:
perception-0-fast,
perception-0-thinking
status
enum<string>

The status of the query. Synchronous queries always return completed status.

Available options:
processing,
completed,
failed
use_preset
boolean

Whether structured output was requested for this query.

question
string | null
Example:

"What's happening in this video?"

short_answer
string | null

Natural language answer. Populated when use_preset is false.

answer_uri
string<uri> | null

URI to full answer when result is too long.

structured_answer
object | null

Structured JSON response when use_preset is true. Reach out to [email protected] to configure structured responses.

feedback
object | null

User feedback

created_at
string<date-time>
Example:

"2026-04-20T12:34:56.000Z"