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

# Get Task Status

> Query video task execution status and retrieve generated video files

# Get Task Status

Query the execution status of video generation tasks and retrieve generated videos when complete.

## Endpoint

```http theme={"dark"}
GET https://api.poyo.ai/api/generate/status/{task_id}
```

## Authentication

All requests require Bearer token authentication:

```bash theme={"dark"}
Authorization: Bearer YOUR_API_KEY
```

## Parameters

### Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `task_id` | string | Yes | Unique task identifier returned from the submit endpoint |

## Response

### Success Response (200)

```json theme={"dark"}
{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165211-xyz789",
    "status": "finished",
    "credits_amount": 20,
    "files": [
      {
        "file_url": "https://storage.poyo.ai/generated/video-xyz789.mp4",
        "file_type": "video"
      }
    ],
    "created_time": "2025-11-12T10:30:00",
    "progress": 100,
    "error_message": null
  }
}
```

### Response Fields

| Field | Type | Description |
| - | - | - |
| `code` | integer | HTTP status code (200 for success) |
| `data.task_id` | string | Unique task identifier |
| `data.status` | string | Task status: `not_started`, `running`, `finished`, `failed` |
| `data.credits_amount` | number | Credits charged for the task |
| `data.files` | array | Generated videos when status is `finished` |
| `data.files[].file_url` | string | Direct URL to generated file |
| `data.files[].file_type` | string | Type of generated file, usually `video` |
| `data.created_time` | string | ISO 8601 timestamp of task creation |
| `data.progress` | integer | Completion percentage (0-100) |
| `data.error_message` | string | Error description when status is `failed` |

### Status Values

| Status | Description |
| - | - |
| `not_started` | Task is queued, waiting to be processed |
| `running` | Task is currently being generated |
| `finished` | Task completed successfully, results available in `files` |
| `failed` | Task failed, error details in `error_message` |

### Failed Task

```json theme={"dark"}
{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165211-xyz789",
    "status": "failed",
    "credits_amount": 0,
    "files": [],
    "created_time": "2025-11-12T10:30:00",
    "progress": 0,
    "error_message": "The prompt violates our content policy"
  }
}
```

## Code Example

```bash theme={"dark"}
curl -X GET https://api.poyo.ai/api/generate/status/task-unified-1757165211-xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Important Notes

> [!TIP]
>
> **Poll Interval**: Check status every 2-5 seconds. Typical video generation takes 90-300 seconds.

> [!WARNING]
>
> **Content Validity**: Generated videos are accessible for **3 days** after creation. Download and save your content promptly.

> [!TIP]
>
> **Webhooks**: Instead of polling, you can provide a `callback_url` when submitting tasks to receive automatic notifications. See [Video Webhook Callbacks](https://docs.poyo.ai/api-manual/task-management/video-webhooks.md).

For code samples in more languages, polling with backoff, and HTTP error codes, see the [unified task status](https://docs.poyo.ai/api-manual/task-management/status.md) page.


## OpenAPI

````yaml api-manual/task-management/video-status.json GET /api/generate/status/{task_id}
openapi: 3.1.0
info:
  title: PoYo AI - Video Task Status API
  description: Query video task execution status and retrieve generated video files
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
security:
  - BearerAuth: []
paths:
  /api/generate/status/{task_id}:
    get:
      tags:
        - Video Task Management
      summary: Query Video Task Status
      operationId: queryVideoTaskStatus
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
          description: Unique task identifier returned from the submit endpoint
      responses:
        '200':
          description: Task status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              examples:
                finished:
                  summary: Finished video task
                  value:
                    code: 200
                    data:
                      task_id: task-unified-1757165211-xyz789
                      status: finished
                      credits_amount: 20
                      files:
                        - file_url: https://storage.poyo.ai/generated/video-xyz789.mp4
                          file_type: video
                      created_time: '2025-11-12T10:30:00'
                      progress: 100
components:
  schemas:
    StatusResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          example: 200
        data:
          $ref: '#/components/schemas/TaskStatus'
      example:
        code: 200
        data:
          task_id: task-unified-1757165211-xyz789
          status: finished
          credits_amount: 20
          files:
            - file_url: https://storage.poyo.ai/generated/video-xyz789.mp4
              file_type: video
          created_time: '2025-11-12T10:30:00'
          progress: 100
    TaskStatus:
      type: object
      properties:
        task_id:
          type: string
        status:
          type: string
          enum:
            - not_started
            - running
            - finished
            - failed
          example: finished
        credits_amount:
          type: number
          description: Credits charged for the task
          example: 20
        files:
          type: array
          items:
            $ref: '#/components/schemas/FileItem'
        created_time:
          type: string
          format: date-time
        progress:
          type: number
          example: 100
        error_message:
          type:
            - string
            - 'null'
      example:
        task_id: task-unified-1757165211-xyz789
        status: finished
        credits_amount: 20
        files:
          - file_url: https://storage.poyo.ai/generated/video-xyz789.mp4
            file_type: video
        created_time: '2025-11-12T10:30:00'
        progress: 100
    FileItem:
      type: object
      required:
        - file_url
        - file_type
      properties:
        label:
          type: string
          description: Optional file label when provided by the model
        file_url:
          type: string
          format: uri
          example: https://storage.poyo.ai/generated/video-xyz789.mp4
        file_type:
          type: string
          enum:
            - image
            - video
            - audio
            - 3d
            - other
          example: video
        format:
          type: string
          description: Optional file format when provided by the model
        content_type:
          type: string
          description: Optional MIME type when provided by the model
        file_name:
          type: string
          description: Optional file name when provided by the model
        file_size:
          type: integer
          description: Optional file size in bytes when provided by the model
      example:
        file_url: https://storage.poyo.ai/generated/video-xyz789.mp4
        file_type: video
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.