> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidnavigator.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.vidnavigator.com/webhooks.md).

> [!NOTE]
>
> Use this endpoint instead of [`POST /watch`](https://docs.vidnavigator.com/api-reference/endpoint/watch.md) 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

**1. Submit the job**

`POST /watch/async` with the **same body** as [`POST /watch`](https://docs.vidnavigator.com/api-reference/endpoint/watch.md), plus an optional `webhook_url`. You get `202 Accepted` with a `task_id` and a `check_status_url`.

**2. Wait for the result**

Poll `GET /watch/{task_id}` every few seconds while `task_status` is `processing`, or receive a [webhook](https://docs.vidnavigator.com/webhooks.md) when the job finishes.

**3. 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`](https://docs.vidnavigator.com/api-reference/endpoint/watch.md#billing): 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](https://docs.vidnavigator.com/api-reference/endpoint/watch.md#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](https://vidnavigator.com/studio/api); pass `""` to opt this job out of the default. Must be a public `https` URL. See [Webhooks](https://docs.vidnavigator.com/webhooks.md). |

> [!NOTE]
>
> `include_usage` is not accepted on the submit request. Pass it on the poll request instead.

```bash cURL
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"
  }'
```

```python Python
from vidnavigator import VidNavigatorClient

client = VidNavigatorClient()

# Returns right away with a handle on the job
job = client.submit_watch_video(
    video_url="https://www.tiktok.com/@nasa/video/7300000000000000000",
    detail="high",
)
print(job.task_id)

# Waits for the job, then returns the same object as watch_video()
result = job.result(include_usage=True)
for scene in result.data.scenes:
    print(f"[{scene.start:.0f}s - {scene.end:.0f}s] {scene.description}")

# Later, or from another process: rebuild the handle from the task_id
result = client.resume_job("watch", job.task_id).result()
```

```javascript JavaScript
const { VidNavigatorClient } = require('vidnavigator');

const vn = new VidNavigatorClient({ apiKey: process.env.VIDNAVIGATOR_API_KEY });

// Returns right away with a handle on the job
const job = await vn.watch.submit({
  video_url: 'https://www.tiktok.com/@nasa/video/7300000000000000000',
  detail: 'high',
});
console.log(job.task_id);

// Waits for the job, then returns the same shape as vn.watch()
const { scenes } = await job.result();
scenes.forEach(scene => console.log(`[${scene.start}s - ${scene.end}s] ${scene.description}`));

// Later, or from another process: reattach from the task_id
const again = await vn.watch.resume(job.task_id).result();
```

### Response (202 Accepted)

```json
{
  "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

> [!NOTE]
>
> 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.

```bash cURL
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](https://docs.vidnavigator.com/api-reference/endpoint/watch.md#success-response-200-ok): `video_info`, `transcript`, `scenes`, `frames_analyzed`, and `transcript_error` when the video has no transcript.

```json
{
  "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](https://vidnavigator.com/studio/api), to be called back when the job finishes with a `watch.completed` or `watch.failed` event. See [Webhooks](https://docs.vidnavigator.com/webhooks.md) for the payload and signature verification, and [Async Jobs](https://docs.vidnavigator.com/guides/async-jobs.md) for the full workflow.

## OpenAPI

````yaml POST /watch/async
openapi: 3.0.3
info:
  title: VidNavigator Developer API
  version: 1.0.0
servers:
  - url: https://api.vidnavigator.com/v1
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /watch/async:
    post:
      summary: Watch a video asynchronously (long videos)
      description: |-
        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.
      operationId: watchVideoAsync
      tags:
        - Watch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - video_url
              properties:
                video_url:
                  type: string
                  format: uri
                  description: URL of the video to watch. For Instagram carousel posts and Snapchat highlights, append ?img_index=N to select a specific video.
                  example: https://www.tiktok.com/@nasa/video/7300000000000000000
                detail:
                  type: string
                  enum:
                    - low
                    - auto
                    - high
                  default: auto
                  description: How 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.
                include_transcript:
                  type: boolean
                  default: true
                  description: When false, only the scenes are returned and no transcript is fetched or produced.
                transcript_text:
                  type: boolean
                  default: false
                  description: When true, returns the transcript as a single plain-text string instead of an array of segments.
                webhook_url:
                  type: string
                  format: uri
                  description: Where 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
                  example: https://example.com/hooks/vidnavigator
      responses:
        "202":
          description: Job accepted and started.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AsyncJobAccepted"
        "400":
          $ref: "#/components/responses/BadRequest"
        "402":
          description: Insufficient credits to queue the job; no task is created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  error:
                    type: string
                    enum:
                      - limit_exceeded
                  error_code:
                    type: string
                    enum:
                      - limit_exceeded
                  message:
                    type: string
        "429":
          description: Too many jobs already running for this account.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  error:
                    type: string
                    enum:
                      - too_many_active_jobs
                  message:
                    type: string
        "500":
          $ref: "#/components/responses/InternalServerError"
components:
  schemas:
    AsyncJobAccepted:
      type: object
      description: 202 response from an async submit endpoint.
      properties:
        status:
          type: string
          enum:
            - success
        data:
          type: object
          properties:
            task_id:
              type: string
              description: Identifier to poll with.
              example: 550e8400-e29b-41d4-a716-446655440000
            task_status:
              type: string
              enum:
                - processing
            job_type:
              type: string
              enum:
                - transcribe
                - extract_video
                - tweet_statement
                - watch
            expires_at:
              type: string
              format: date-time
              description: Results are deleted after this time. Until the job finishes this is a provisional submit-time bound; on completion it is pushed out to finish time + 1 hour.
            check_status_url:
              type: string
              description: Relative URL to poll for status and the result.
              example: /v1/transcribe/550e8400-e29b-41d4-a716-446655440000
            webhook_url:
              type: string
              nullable: true
              description: The URL this job's result will be POSTed to, or null if no webhook applies.
            message:
              type: string
            docs_url:
              type: string
  responses:
    BadRequest:
      description: Bad request - invalid parameters. On /transcribe the `error` field may be `missing_parameter`, `unsupported_platform`, `unsupported_url`, `invalid_url`, `request_body_required`, `video_too_long`, or `no_videos_found` (the post carries no video).
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
              message:
                type: string
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - metadata_fetch_failed
                  - audio_extraction_failed
                  - transcription_failed
                  - internal_server_error
              message:
                type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication. Include your VidNavigator API key in the X-API-Key header.
````
