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

# Get video status

> Check whether a submitted video is `processing`, `ready` or `failed`. Free to call.

`ready` means the ingest finished. It does not mean `POST /v1/match` will answer
synchronously. The engine analysis that gates the synchronous path is persisted after
this row flips to `ready`.




## OpenAPI

````yaml /api-reference/openapi.yaml get /v1/videos/{video_id}
openapi: 3.1.0
info:
  title: Cue API
  version: 1.0.0
  description: >
    Match licensed music to a video, or to a script. Five things it does:
    **match** music to

    an analyzed video, **underscore** a text script with no video at all,
    **sync** a track to

    the moments in a clip, **loop** a short track across a long one, and map a
    track's

    **beats** and downbeats. Videos are ingested once and reused by match, sync
    and loop;

    underscore and beats take no video at all.


    Responses carry timings and catalog identifiers, not recordings. You resolve
    a track through

    your own catalog access and render it yourself.


    Work that is already cached answers `200`. Work that needs a first-time
    build answers `202`,

    in one of two shapes: a JOB (`job_id` plus a job URL) or a VIDEO STILL
    INGESTING (`video_id`

    and a `/v1/videos/{id}` URL, with no `job_id`). Branch on whether `job_id`
    is present.


    All requests authenticate with an API key, sent either as `Authorization:
    Bearer vbsk_...`

    or in an `x-api-key` header. Both work. Keys are created in the

    [developer portal](https://cue.vibeset.ai/developer).
servers:
  - url: https://cue.vibeset.ai
    description: Production
security:
  - bearerAuth: []
  - apiKeyAuth: []
tags:
  - name: Match
    description: Match music to a video.
  - name: Underscore
    description: Match music to a script, no video needed.
  - name: Sync
    description: Get sync points, where a track lands with a video.
  - name: Loop
    description: Loop a short track seamlessly across a long video.
  - name: Beats
    description: Map the beat and downbeat grid of any audio you can point us at.
  - name: Videos
    description: Ingest and check the status of videos.
paths:
  /v1/videos/{video_id}:
    get:
      tags:
        - Videos
      summary: Get video status
      description: >
        Check whether a submitted video is `processing`, `ready` or `failed`.
        Free to call.


        `ready` means the ingest finished. It does not mean `POST /v1/match`
        will answer

        synchronously. The engine analysis that gates the synchronous path is
        persisted after

        this row flips to `ready`.
      operationId: getVideo
      parameters:
        - name: video_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The video's current status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    VideoStatus:
      type: object
      properties:
        video_id:
          type: string
        status:
          type: string
          enum:
            - processing
            - ready
            - failed
        ready:
          type: boolean
        title:
          type:
            - string
            - 'null'
        reason:
          type:
            - string
            - 'null'
          description: >-
            Why a `failed` video failed, machine-readable, e.g.
            `insufficient_credits`. Null on every other status.
    Error:
      type: object
      description: Every `/v1` error body has this shape.
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request
                - authentication_error
                - payment_required
                - forbidden
                - not_found
                - conflict
                - payload_too_large
                - unsupported_media_type
                - rate_limited
                - internal_error
                - upstream_error
                - service_unavailable
                - error
              description: >-
                A stable machine-readable type. Branch on this, not on the
                message.
            message:
              type: string
              description: A human-readable explanation of what went wrong.
            request_id:
              type:
                - string
                - 'null'
              description: >-
                The same value as the `X-Request-Id` response header. Quote it
                to support.
            details:
              type: array
              description: >-
                Present only on a request-validation `422`, listing which fields
                were invalid.
              items:
                type: object
      example:
        error:
          type: invalid_request
          message: Provide either 'video_id' or 'video_url'.
          request_id: a1b2c3d4e5f6
  responses:
    Unauthorized:
      description: The key is missing, invalid, expired or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        The key can't access this resource, the video or job belongs to another
        account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No such video or job.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your API key as a Bearer token, e.g. `Authorization: Bearer
        vbsk_live_...`
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Your API key in the x-api-key header, e.g. `x-api-key: vbsk_live_...`'

````