Polling vs webhooks for extraction jobs
Poll within your rate limit or receive signed webhooks when a job settles. When to use each, and which event to collect results on.
Polling
Ask for the job until its status is no longer queued or processing, which is when each video’s rows arrive. A single video usually settles in under a minute, most of it spent fetching captions, so polling is perfectly reasonable for a handful of videos and for anything you are debugging by hand.
429, wait for the seconds in Retry-After. For a batch, poll the one job id and watch its counts; there is nothing per video to poll.Webhooks
Register an endpoint and we post to it as each video reaches done or failed, and once more with batch.completed when the whole job has settled. That last one is the signal to collect: read the job by its batch_id. Events carry ids and status, never the rows, which keeps the read-once rule in one place and means a leaked webhook body contains no extracted data.
Webhooks are included on every paid plan. Set one up on the webhooks screen. Payload shapes and signing are in webhook payloads.
Which to use
You are submitting a few videos, you are on the Free plan, or you have nowhere public to receive a callback.
You are running batches of hundreds, or the work that consumes the rows is a background job anyway.