Watch Online Video (Async)
Queue a video to watch and return a task_id immediately.
Use this instead of POST /watch for anything longer than ~10 minutes.
Accepts the same body as POST /watch, plus webhook_url.
include_usage is not accepted here: pass it on GET /watch/{task_id} once task_status=completed.
See https://docs.vidnavigator.com/guides/async-jobs
Submit-time check: the submit endpoint returns 402 instead of a task_id when the account has almost no credits left. A job can still fail later with 402 when the video needs more than the remaining balance. An invalid or deactivated API key is rejected with 401, and a key without the endpoint's permission with 403; no task is created in either case.
Videos longer than 2 hours are not accepted (video_too_long), except on YouTube.
Watch an online video of up to 2 hours (any length on YouTube). The job runs in the background: you get a task_id immediately, then collect the scenes and the transcript by polling or through a webhook.
Use this endpoint instead of POST /watch for media longer than 10 minutes, which the synchronous endpoint rejects with video_too_long. It also works for short videos, so it is the safe default when you don't know the duration.
How It Works
Submit the job
POST /watch/async with the same body as POST /watch, plus an optional webhook_url. You get 202 Accepted with a task_id and a check_status_url.
Wait for the result
Poll GET /watch/{task_id} every few seconds while task_status is processing, or receive a webhook when the job finishes.
Read the result
On completed, data.result is identical to the synchronous response's data block, so the same parsing code works for both. On failed, data.error carries the same error code the synchronous endpoint would have returned.
Billing
Billed exactly like POST /watch: the fetch of the video, the transcription when the video has no captions, and 1 credit per 1,000 frames analyzed. The async mode costs nothing extra. Charges are made while the job runs, so pass include_usage=true on the result request (not on the submit) to see them. A failed job has all of its charges reverted.
Submit the job
POST https://api.vidnavigator.com/v1/watch/async
| Parameter | Type | Required | Description |
|---|---|---|---|
video_url | string | Yes | URL of the video to watch. For Instagram carousel posts and Snapchat highlights, append ?img_index=N to select a specific video. |
detail | string | No | How closely the picture is followed: low, auto (default) or high. See Level of detail. |
include_transcript | boolean | No | Default true. When false, only the scenes are returned and no transcript is fetched or produced. |
transcript_text | boolean | No | When true, returns the transcript as a single plain-text string. |
webhook_url | string | No | Where to POST the result when the job finishes. Overrides the account default set in Studio → API; pass "" to opt this job out of the default. Must be a public https URL. See Webhooks. |
include_usage is not accepted on the submit request. Pass it on the poll request instead.
curl -X POST "https://api.vidnavigator.com/v1/watch/async" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://www.tiktok.com/@nasa/video/7300000000000000000",
"webhook_url": "https://example.com/hooks/vidnavigator"
}'Response (202 Accepted)
{
"status": "success",
"data": {
"task_id": "550e8400-e29b-41d4-a716-446655440000",
"task_status": "processing",
"job_type": "watch",
"expires_at": "2026-11-15T13:00:00Z",
"check_status_url": "/v1/watch/550e8400-e29b-41d4-a716-446655440000",
"webhook_url": "https://example.com/hooks/vidnavigator",
"message": "Job started. Poll check_status_url for the result."
}
}| Status | error | Description |
|---|---|---|
400 | missing_parameter, invalid_parameter, … | Invalid request. |
401 | — | Invalid or deactivated API key. |
402 | limit_exceeded | The account has almost no credits left. No task is created. |
403 | — | The API key lacks permission for this endpoint. |
429 | too_many_active_jobs | Too many jobs already running for this account. |
Get the result
The playground above only covers the submit request. Call the result endpoint with cURL or your HTTP client.
GET https://api.vidnavigator.com/v1/watch/{task_id}
| Parameter | In | Required | Description |
|---|---|---|---|
task_id | path | Yes | The task_id returned by POST /watch/async. |
include_usage | query | No | When true and task_status=completed, attaches a usage block with the final charges. |
Poll every few seconds while task_status is processing. Results are kept for 1 hour after the job finishes, and reading a task doesn't delete it.
curl "https://api.vidnavigator.com/v1/watch/550e8400-e29b-41d4-a716-446655440000?include_usage=true" \
-H "X-API-Key: YOUR_API_KEY"On completed, data.result is identical to the data block of the synchronous response: video_info, transcript, scenes, frames_analyzed, and transcript_error when the video has no transcript.
{
"status": "success",
"data": {
"task_id": "550e8400-e29b-41d4-a716-446655440000",
"task_status": "completed",
"job_type": "watch",
"request": { "video_url": "https://www.tiktok.com/@nasa/video/7300000000000000000", "detail": "auto", "include_transcript": true, "transcript_text": false },
"created_at": "2026-11-15T12:00:00Z",
"started_at": "2026-11-15T12:00:01Z",
"completed_at": "2026-11-15T12:00:19Z",
"expires_at": "2026-11-15T13:00:19Z",
"check_status_url": "/v1/watch/550e8400-e29b-41d4-a716-446655440000",
"webhook": { "status": "delivered", "attempts": 1, "response_status": 200, "last_error": null, "delivered_at": "2026-11-15T12:00:20Z" },
"result": {
"video_info": { "title": "Evening news", "duration": 24.0, "url": "https://www.tiktok.com/@nasa/video/7300000000000000000" },
"transcript": [
{ "text": "Good evening. Tonight, the storm reaches the coast.", "start": 0.4, "end": 3.9 }
],
"scenes": [
{ "start": 4.0, "end": 12.0, "description": "A presenter stands in front of a world map and points at Europe.", "on_screen_text": "BREAKING NEWS" }
],
"frames_analyzed": 23
},
"error": null
}
}On failed, data.result is null and data.error carries the same code the synchronous endpoint would have returned, e.g. { "error": "frames_not_available", "message": "...", "http_status": 404 }.
| Status | error | Description |
|---|---|---|
404 | task_not_found | Unknown task_id, expired, owned by another account, or not a watch task. |
Webhook
Pass webhook_url on the submit request, or configure a default endpoint in Studio → API, to be called back when the job finishes with a watch.completed or watch.failed event. See Webhooks for the payload and signature verification, and Async Jobs for the full workflow.
API reference
ApiKeyAuthX-API-Key<token>API key authentication. Include your VidNavigator API key in the X-API-Key header.
application/json- body
video_url*stringURL of the video to watch. For Instagram carousel posts and Snapchat highlights, append ?img_index=N to select a specific video.
uridetail?stringHow closely the picture is followed. At every level a frame is taken where the picture changes, and at least one every 10 seconds; the level sets how small a change counts. low keeps the larger changes, auto is the balanced default, high follows faster cuts and looks at a still picture twice as often. A higher level analyzes more frames on a video whose picture changes often.
"auto""low""auto""high"include_transcript?booleanWhen false, only the scenes are returned and no transcript is fetched or produced.
truetranscript_text?booleanWhen true, returns the transcript as a single plain-text string instead of an array of segments.
falsewebhook_url?stringWhere to POST the result when the job finishes. Overrides the account-level default configured in Studio → API. Pass an empty string to opt this job out of that default. Must be a publicly reachable https URL — private, loopback and link-local hosts are rejected. See https://docs.vidnavigator.com/guides/webhooks
uriJob accepted and started.
application/json- response
202 response from an async submit endpoint.
status?"success""success"data?curl -X POST 'https://api.vidnavigator.com/v1/watch/async' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://www.tiktok.com/@nasa/video/7300000000000000000"}'{ "status": "success", "data": { "task_id": "550e8400-e29b-41d4-a716-446655440000", "task_status": "processing", "job_type": "transcribe", "expires_at": "2019-08-24T14:15:22Z", "check_status_url": "/v1/transcribe/550e8400-e29b-41d4-a716-446655440000", "webhook_url": "string", "message": "string", "docs_url": "string" }}