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

# List Jobs

> List all jobs for the authenticated user

## Overview

Returns a paginated list of jobs with optional status filtering. Jobs are returned in reverse chronological order (newest first).

## Header Parameters

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication
</ParamField>

## Query Parameters

<ParamField query="limit" type="integer" default="20">
  Number of jobs to return. Maximum: 100
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of jobs to skip for pagination
</ParamField>

<ParamField query="status" type="string">
  Filter by job status: `pending`, `processing`, `completed`, `failed`, `warning`
</ParamField>

## Response

<ResponseField name="jobs" type="array">
  Array of job objects
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of jobs (ignoring filters)
</ResponseField>

<ResponseField name="limit" type="integer">
  Number of jobs requested
</ResponseField>

<ResponseField name="offset" type="integer">
  Number of jobs skipped
</ResponseField>

### Job Object

<ResponseField name="id" type="string">
  Job UUID
</ResponseField>

<ResponseField name="url" type="string">
  Original video URL
</ResponseField>

<ResponseField name="status" type="string">
  Job status: `Pending`, `Processing`, `Completed`, `Failed`, `Warning`, `Skipped`
</ResponseField>

<ResponseField name="s3_key" type="string">
  S3 object key (when completed)
</ResponseField>

<ResponseField name="error" type="string">
  Error message (when failed)
</ResponseField>

<ResponseField name="error_type" type="string">
  Error classification (when failed): `error` for technical failures (rate limits, bot detection, connection issues), `warning` for content issues (private video, members-only, geo-blocked, unavailable)
</ResponseField>

<ResponseField name="step" type="string">
  Current processing step: `Queued`, `Downloading`, `Muxing`, `Uploading`, `Finished`
</ResponseField>

<ResponseField name="created_at" type="integer">
  Creation timestamp (milliseconds since epoch)
</ResponseField>

<ResponseField name="finished_at" type="integer">
  Completion timestamp (milliseconds since epoch)
</ResponseField>

<ResponseField name="file_size" type="integer">
  File size in bytes (when completed)
</ResponseField>

## Examples

<CodeGroup>
  ```bash List All Jobs theme={null}
  curl -X GET "https://api.tornadoapi.io/jobs" \
    -H "x-api-key: sk_your_api_key"
  ```

  ```bash With Pagination theme={null}
  curl -X GET "https://api.tornadoapi.io/jobs?limit=50&offset=100" \
    -H "x-api-key: sk_your_api_key"
  ```

  ```bash Filter by Status theme={null}
  curl -X GET "https://api.tornadoapi.io/jobs?status=completed" \
    -H "x-api-key: sk_your_api_key"
  ```

  ```bash Failed Jobs Only theme={null}
  curl -X GET "https://api.tornadoapi.io/jobs?status=failed&limit=10" \
    -H "x-api-key: sk_your_api_key"
  ```
</CodeGroup>

## Success Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "jobs": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "status": "Completed",
        "s3_key": "videos/my-video.mp4",
        "error": null,
        "error_type": null,
        "step": "Finished",
        "created_at": 1705507200000,
        "finished_at": 1705507260000,
        "file_size": 52428800
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "url": "https://www.youtube.com/watch?v=abc123",
        "status": "Processing",
        "s3_key": null,
        "error": null,
        "error_type": null,
        "step": "Downloading",
        "created_at": 1705507100000,
        "finished_at": null,
        "file_size": null
      }
    ],
    "total": 142,
    "limit": 20,
    "offset": 0
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "error": "Missing x-api-key header"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Invalid API Key"
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "error": "Database query failed"
  }
  ```
</ResponseExample>