How to analyse a long video asynchronously

Ask the question with an idempotency_key, so a scheduler that runs twice pays once. A long video is read in sections side by side rather than in one pass, so the first answer takes a minute or two and every question after it, carrying the session_id, comes back in about a second.

Last updated 31 August 2026

The call

Copy this as it stands. “How do I survey a two-hour recording from a backend job?” is the question it answers.

TypeScript SDKts

const survey = await playhead.ask({
  url,
  question: "what happens in this recording, section by section",
  idempotency_key: `weekly-report-${week}`,
});

// Keep the session with the report. Next week's questions about the same
// recording are a fraction of the price.
await store.put(week, { session: survey.session_id, answer: survey.answer });

cURLbash

SESSION=$(curl -sX POST https://api.tryplayhead.com/v1/watch_video \
  -H "Authorization: Bearer $PLAYHEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "…", "idempotency_key": "weekly-report-42"}' | jq -r .session_id)

# Every question after the first one carries the session and is short.
curl -sX POST https://api.tryplayhead.com/v1/watch_video \
  -H "Authorization: Bearer $PLAYHEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"session_id\": \"$SESSION\", \"question\": \"who speaks, and when\"}" | jq -r .answer

Watch out for

Everything the API can refuse, and what to send instead, is on the errors page.