Custom query
Ask your own questions about a video and get answers with timestamps.
custom_query answers the questions you write, reading the picture as well as the words. It is the same analysis pass that produces a summary, pointed at your prompt instead of a canned one — so it sees the frames and, when the job also transcribed the video, the speech.
Pass your questions in queries. A custom_query job with an empty queries array is rejected with INVALID_CAPABILITIES (422), because there would be nothing to answer.
Custom query analyzes frames, so it uses your plan's standard video ceiling — 1 minute on Free, 3 on Starter, 10
on Pro, 20 on Scale. Longer videos fail with VIDEO_TOO_LONG. How many questions one job may carry is also
plan-gated: 3 on Free, 10 on every paid plan. Over that limit the job is rejected with TOO_MANY_QUERIES (422).
queries works alongside any capability, not only this one. Ask for transcription and pass questions and you get both. Requesting custom_query explicitly is how you say "questions are the whole point of this job" and guarantee the frames it needs get extracted.
curl -X POST https://api.netraflow.com/v1/jobs \
-H "Content-Type: application/json" \
-H "X-Api-Key: sk_live_your_key_here" \
-d '{
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"capabilities": ["custom_query", "transcription"],
"queries": [
"Is a price shown on screen at any point?",
"What is the presenter wearing?"
]
}'{
"data": {
"job_id": "job_abc123",
"status": "completed",
"queries": [
"Is a price shown on screen at any point?",
"What is the presenter wearing?"
],
"results": {
"query_results": [
{
"query": "Is a price shown on screen at any point?",
"answer": "Yes. A price card reading \"£49.99\" is on screen from about 0:31 to 0:36, lower right.",
"evidence": [{ "timestamp": 31.4, "text": "price card visible, lower right" }]
},
{
"query": "What is the presenter wearing?",
"answer": "A black trench coat over a light shirt for the whole video.",
"evidence": [{ "timestamp": 4.0, "text": "full-body shot of the presenter" }]
}
]
}
}
}Response fields
Answers land in results.query_results, one entry per question, in the order you asked them.
| Prop | Type | Description |
|---|---|---|
| query | string | Your question, echoed back so answers can be matched to questions without relying on order. |
| answer | string | The answer in plain prose. A question the video cannot settle is answered as such rather than guessed. |
| evidence | { timestamp, text }[] | Moments the answer rests on: seconds into the video, and what was there. |
Questions that are refused
A question that reads as an attempt to change the model's instructions rather than ask about the video is rejected up front with INVALID_QUERY (422), and the response names which one by index. Rephrase it as a question about the video's content.