---
title: Submit a video-info job | Vid Kraken API
description: Queue a job that fetches metadata for a YouTube video — title and duration.
url: https://vidkraken.com/docs/endpoint/submit-video-info
updated: '2026-10-24'
---

# Submit a video-info job

For AI agents: docs index at https://vidkraken.com/docs/llms.txt; any page as Markdown by adding .md to its URL.

`POST https://vidkraken.com/api/v2/info`

Queue a job that fetches metadata for a YouTube video — title and
duration. Returns a `jobId` that you poll on `GET /info/{jobId}`.

Set `includeAudioTracks: true` to also resolve the list of available
audio tracks (original + dubbed languages, if any). Audio tracks
require a full extraction, which is slower and can occasionally fail
on hard-to-reach videos — only request them when you need to pick an
audio language ahead of a download.

Useful for showing video details in your UI before queueing a
download, or for picking an audio language ahead of time.

Job state is kept in Redis with a 1-hour TTL — make sure to
poll within that window.

**Cost:** 1 info request from your plan's info quota, on
success only. No bandwidth cost. Failures are not charged.

```bash
curl -X POST "https://vidkraken.com/api/v2/info" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://youtu.be/dQw4w9WgXcQ"}'
```

## Authorization

Bearer token. API key issued from the dashboard, sent as `Authorization: Bearer YOUR_API_KEY`. Get a key at https://vidkraken.com/login.

## Parameters

- `Idempotency-Key` (header, string)

  Optional. A unique string (e.g. a UUID), up to 255 visible ASCII
  characters. Retrying with the same key and body within 24 hours
  returns the original response instead of creating a second job.

  Example: `4f1c9a2e-8d3b-4c7a-9f0e-2b6d5a1c3e7f`.

## Request body

- `url` (string, required)

  YouTube video URL. Supported patterns:

  - `https://youtube.com/watch?v=ID`

  - `https://youtu.be/ID`

  - `https://youtube.com/live/ID`

- `includeAudioTracks` (boolean)

  When `true`, the result also lists the video's available audio
  tracks (`audio`) — original + dubbed languages. This requires a
  full extraction, so it is slower than a plain metadata request.
  When omitted or `false`, `audio` is absent from the result.

  Default: `false`.

### Examples

```json
{
  "url": "https://youtu.be/dQw4w9WgXcQ"
}
```

## Responses

### 200

Job enqueued.

Headers:

- `Idempotent-Replayed`: `true` when this response is a replay of an earlier request with the same Idempotency-Key.

- `jobId` (string (uuid), required)

  Unique ID for the video-info job. Use this to poll the status endpoint.

- `status` (string, required)

  One of: `pending`.

```json
{
  "jobId": "6f9c1234-5e8a-4b2f-9c1e-0a7b69cfc45e",
  "status": "pending"
}
```

### 400

Invalid input — missing or malformed field.

Body: `ApiError`.

missing-url:

```json
{
  "error": "Missing required field: url",
  "code": "INVALID_REQUEST"
}
```

bad-format:

```json
{
  "error": "Invalid format. Must be one of: 1080, 720, 480, 360, audio",
  "code": "INVALID_REQUEST"
}
```

live-in-progress:

```json
{
  "error": "Live on-going videos are not supported. Try again after the live stream ends.",
  "code": "INVALID_REQUEST"
}
```

too-long:

```json
{
  "error": "This video is too long to download in audio-aac (21,812 hours, about 1,265 GB; the limit is 100 GB per file).",
  "code": "INVALID_REQUEST"
}
```

### 401

Missing or invalid API key.

Body: `ApiError`.

missing:

```json
{
  "error": "Missing API key. Provide it as 'Bearer YOUR_API_KEY'",
  "code": "UNAUTHORIZED"
}
```

invalid:

```json
{
  "error": "Invalid API key",
  "code": "UNAUTHORIZED"
}
```

### 403

Usage limit reached for the current plan — the bandwidth
allowance (plus any overage allowance) or a request quota is
exhausted. Upgrade or wait for the next billing cycle. The
error string is `Credit limit reached` for backwards
compatibility.

Body: `ApiError`.

```json
{
  "error": "Credit limit reached",
  "code": "LIMIT_REACHED"
}
```

### 409

A request with this Idempotency-Key is still being processed. Retry after `Retry-After` seconds.

Headers:

- `Retry-After`: Seconds to wait before retrying.

Body: `ApiError`.

```json
{
  "error": "A request with this Idempotency-Key is still being processed. Retry shortly.",
  "code": "IDEMPOTENCY_CONFLICT"
}
```

### 422

This Idempotency-Key was already used with a different request body.

Body: `ApiError`.

```json
{
  "error": "This Idempotency-Key was already used with a different request body. Use a new key.",
  "code": "IDEMPOTENCY_KEY_REUSED"
}
```

### 500

Unexpected server error.

Body: `ApiError`.

```json
{
  "error": "Failed to enqueue download job",
  "code": "INTERNAL_ERROR"
}
```

## Schemas

### `ApiError`

- `error` (string, required)

  Human-readable error message.

- `code` (string, required)

  Machine-readable error code; branch on this rather than on
  `error`. New codes may be added, so treat an unknown one by
  its HTTP status. See the table under Errors in the API
  description for what each one means.

  One of: `INVALID_REQUEST`, `UNAUTHORIZED`, `LIMIT_REACHED`, `NOT_FOUND`, `VIDEO_NOT_FOUND`, `IDEMPOTENCY_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`, `TOO_MANY_PENDING`, `INTERNAL_ERROR`, `UNAVAILABLE`.

- `details` (string)

  Optional extra context — e.g. yt-dlp's error message on `500`s.

Full API reference, including the download.finished webhook: https://vidkraken.com/docs.md · OpenAPI: https://vidkraken.com/openapi.json