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

# Get Task Status

> Retrieve the current status of a video generation task

Retrieves the current status of a video generation task. Poll this endpoint to check when your video is ready.

## Path Parameters

<ParamField path="taskId" type="string" required>
  The unique identifier of the task, returned when creating a slideshow.

  Example: `task_abc123xyz`
</ParamField>

## Response

The response varies based on the task status:

### Common Fields

<ResponseField name="task_id" type="string" required>
  Unique identifier for the task.
</ResponseField>

<ResponseField name="status" type="string" required>
  Current task status: `queued`, `processing`, `completed`, or `failed`.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  Task creation timestamp (ISO 8601 format).
</ResponseField>

<ResponseField name="livemode" type="boolean" required>
  `true` for tasks created with a live (`vpk_live_`) key; `false` for test-mode (`vpk_test_`) sandbox tasks.

  <Note>
    Test and live tasks are isolated: a `vpk_test_` key can only read test tasks and a `vpk_live_` key can only read live tasks. Reading a task created with the other key type returns the same `404 TASK_NOT_FOUND` as a missing task. See [Test Mode](/concepts/test-mode).
  </Note>
</ResponseField>

### Queued Status

<ResponseField name="queue_position" type="integer">
  Position in the processing queue.
</ResponseField>

<ResponseField name="estimated_completion" type="string">
  Estimated completion time (ISO 8601 format).
</ResponseField>

### Processing Status

<ResponseField name="started_at" type="string">
  When processing began (ISO 8601 format).
</ResponseField>

### Completed Status

<ResponseField name="completed_at" type="string">
  When processing finished (ISO 8601 format).
</ResponseField>

<ResponseField name="result" type="object">
  The video generation result.

  <Expandable title="Result properties">
    <ResponseField name="result.video_url" type="string">
      URL to download the generated video.
    </ResponseField>

    <ResponseField name="result.cover_image_url" type="string">
      URL to the cover image (first frame of the video). Use this as a thumbnail or preview for the video.
    </ResponseField>

    <ResponseField name="result.duration_seconds" type="integer">
      Video duration in seconds.
    </ResponseField>

    <ResponseField name="result.resolution" type="string">
      Video resolution (e.g., "1080p").
    </ResponseField>

    <ResponseField name="result.expires_at" type="string">
      When the video URL expires (ISO 8601 format). URLs expire after 7 days.
    </ResponseField>
  </Expandable>
</ResponseField>

### Failed Status

<ResponseField name="error" type="object">
  Error details when the task failed.

  <Expandable title="Error properties">
    <ResponseField name="error.code" type="string">
      Machine-readable error code.
    </ResponseField>

    <ResponseField name="error.message" type="string">
      Human-readable error description.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.vibepeak.ai/v1/tasks/task_abc123xyz \
    -H "Authorization: Bearer vpk_live_xxxxx"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.vibepeak.ai/v1/tasks/task_abc123xyz', {
    headers: {
      'Authorization': 'Bearer vpk_live_xxxxx'
    }
  });

  const task = await response.json();
  console.log(`Status: ${task.status}`);

  if (task.status === 'completed') {
    console.log(`Video URL: ${task.result.video_url}`);
    console.log(`Cover Image: ${task.result.cover_image_url}`);
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.vibepeak.ai/v1/tasks/task_abc123xyz',
      headers={
          'Authorization': 'Bearer vpk_live_xxxxx'
      }
  )

  task = response.json()
  print(f"Status: {task['status']}")

  if task['status'] == 'completed':
      print(f"Video URL: {task['result']['video_url']}")
      print(f"Cover Image: {task['result']['cover_image_url']}")
  ```
</RequestExample>

<ResponseExample>
  ```json Queued theme={null}
  {
    "task_id": "task_abc123xyz",
    "status": "queued",
    "queue_position": 2,
    "estimated_completion": "2026-01-04T12:30:00Z",
    "created_at": "2026-01-04T12:00:00Z"
  }
  ```

  ```json Processing theme={null}
  {
    "task_id": "task_abc123xyz",
    "status": "processing",
    "created_at": "2026-01-04T12:00:00Z",
    "started_at": "2026-01-04T12:05:00Z"
  }
  ```

  ```json Completed theme={null}
  {
    "task_id": "task_abc123xyz",
    "status": "completed",
    "created_at": "2026-01-04T12:00:00Z",
    "started_at": "2026-01-04T12:05:00Z",
    "completed_at": "2026-01-04T12:15:00Z",
    "livemode": true,
    "result": {
      "video_url": "https://storage.vibepeak.ai/videos/task_abc123xyz.mp4",
      "cover_image_url": "https://storage.googleapis.com/vibepeak-audio/covers/task_abc123xyz.jpg",
      "duration_seconds": 45,
      "resolution": "1080p",
      "expires_at": "2026-01-11T12:15:00Z"
    }
  }
  ```

  ```json Completed (Test Mode) theme={null}
  {
    "task_id": "task_abc123xyz",
    "status": "completed",
    "created_at": "2026-01-04T12:00:00Z",
    "started_at": "2026-01-04T12:00:05Z",
    "completed_at": "2026-01-04T12:00:05Z",
    "livemode": false,
    "result": {
      "video_url": "https://storage.vibepeak.ai/samples/sample-landscape.mp4",
      "cover_image_url": "https://storage.vibepeak.ai/samples/sample-cover.jpg",
      "duration_seconds": 12,
      "total_scenes": 3
    }
  }
  ```

  ```json Failed theme={null}
  {
    "task_id": "task_abc123xyz",
    "status": "failed",
    "created_at": "2026-01-04T12:00:00Z",
    "started_at": "2026-01-04T12:05:00Z",
    "completed_at": "2026-01-04T12:06:00Z",
    "error": {
      "code": "IMAGE_PROCESSING_FAILED",
      "message": "Failed to process image at index 2: Invalid image format"
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": {
      "code": "TASK_NOT_FOUND",
      "message": "Task not found.",
      "request_id": "req_xyz123"
    }
  }
  ```
</ResponseExample>

## Polling Best Practices

<Warning>
  Don't poll too frequently. We recommend polling every 5-15 seconds.
</Warning>

Here's a recommended polling implementation:

```javascript theme={null}
async function waitForCompletion(taskId, apiKey) {
  const maxAttempts = 60;
  const pollInterval = 5000; // 5 seconds

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(
      `https://api.vibepeak.ai/v1/tasks/${taskId}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    );

    const task = await response.json();

    switch (task.status) {
      case 'completed':
        return task.result;
      case 'failed':
        throw new Error(`Task failed: ${task.error.message}`);
      case 'queued':
      case 'processing':
        await new Promise(r => setTimeout(r, pollInterval));
        break;
    }
  }

  throw new Error('Task timed out');
}

// Usage
const result = await waitForCompletion('task_abc123xyz', apiKey);
console.log(`Video ready: ${result.video_url}`);
```

## Error Codes

| Code              | Status | Description                                   |
| ----------------- | ------ | --------------------------------------------- |
| `TASK_NOT_FOUND`  | 404    | Task doesn't exist or belongs to another user |
| `INVALID_API_KEY` | 401    | Invalid or missing API key                    |

See [Error Handling](/concepts/error-handling) for more details.

## Video URL Expiration

<Info>
  Video URLs expire after **7 days**. Download or store the video before the `expires_at` timestamp.
</Info>

If you need the video after expiration:

1. Re-request the task status (if the video is still available in storage)
2. Create a new slideshow with the same images