How to analyse a long video asynchronously

Pass sync false and the call returns a job_id straight away instead of waiting. Poll GET /v1/jobs/{id} or give a webhook_url and get called once when it settles. The overview level is the right one for a first pass over anything long — it packs a minute of video into a sheet instead of six seconds.

Last updated 6 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 { job_id } = await playhead.frames({
  url,
  detail: "overview",
  sync: false,
  idempotency_key: `weekly-report-${week}`,
});

const job = await playhead.waitFor(job_id, {
  interval: 5_000,
  onPoll: (job) => console.log(job.status),
});

console.log(job.result?.coverage);

cURLbash

JOB=$(curl -sX POST https://api.tryplayhead.com/v1/frames \
  -H "Authorization: Bearer $PLAYHEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "…", "detail": "overview", "sync": false}' | jq -r .job_id)

curl -s https://api.tryplayhead.com/v1/jobs/$JOB \
  -H "Authorization: Bearer $PLAYHEAD_API_KEY" | jq .status

Watch out for

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