---
title: "List tasks"
method: GET
path: "/v1/tasks"
tags: ["Tasks"]
---

# List tasks

`GET /v1/tasks`

## Request

- Base URL: `https://api.hotapi.ai`
- URL: `https://api.hotapi.ai/v1/tasks`
- Auth: HTTP bearer

List the organization's tasks, most recent first, with cursor pagination. Filter by `status` (or `active`), `api_key_id`, and a `created_after`/`created_before` range; pass `fields=summary` to leave out `input`/`output` (recommended for polling — then fetch `GET /v1/tasks/{id}` for the payload).

## Query parameters

- `limit` string
- `cursor` string
- `status` string
- `q` string
- `fields` string
- `api_key_id` string
- `created_after` string
- `created_before` string

## Response `200`

A page of tasks. `fields=full` (default) returns TaskList; `fields=summary` returns TaskListSummary.

- union: A page of tasks. `fields=full` (default) returns TaskList; `fields=summary` returns TaskListSummary.
  - object: A page of tasks, most recent first.
    - `data` object[], required
      - `id` string, required
      - `object` 'task', required
      - `status` union, required: Lifecycle status. Terminal states: succeeded | failed | cancelled | expired.
        - 'pending'
        - 'queued'
        - 'processing'
        - 'succeeded'
        - 'failed'
        - 'cancelled'
        - 'expired'
      - `model` string, required
      - `task_kind` string, required
      - `input` object, required: The normalized request input the task was created with.
      - `output` object: Result payload, present once status=succeeded. Contains hosted asset URLs (re-hosted on our CDN).
      - `error` object
        - `type` string, required
        - `code` string, required
        - `message` string, required
      - `estimated_credits_cost` integer, required: Credits charged up-front when the task was created (1000 credits = $1).
      - `reference_video_seconds` number: Input-video seconds measured and frozen at submission; reused for draft finalization billing. Zero when no reference video was supplied.
      - `actual_credits_cost` integer: Final credits charged after settlement (equals estimate today).
      - `webhook_url` string, uri
      - `api_key_id` string: The organization's API key that created the task; absent for dashboard/session-created tasks.
      - `created_at` integer, required: Unix seconds.
      - `queued_at` integer: Unix seconds.
      - `started_at` integer: Unix seconds.
      - `completed_at` integer: Unix seconds.
      - `expires_at` integer, required: Unix seconds; result + asset retention deadline.
    - `next_cursor` string, nullable, required: Cursor for the next page, or null when there are no more results.
  - object: A page of task summaries (`fields=summary`), most recent first.
    - `data` object[], required
      - `id` string, required
      - `object` 'task', required
      - `status` union, required: Lifecycle status. Terminal states: succeeded | failed | cancelled | expired.
        - 'pending'
        - 'queued'
        - 'processing'
        - 'succeeded'
        - 'failed'
        - 'cancelled'
        - 'expired'
      - `model` string, required
      - `task_kind` string, required
      - `error` object
        - `type` string, required
        - `code` string, required
        - `message` string, required
      - `estimated_credits_cost` integer, required: Credits charged up-front when the task was created (1000 credits = $1).
      - `reference_video_seconds` number: Input-video seconds measured and frozen at submission; reused for draft finalization billing. Zero when no reference video was supplied.
      - `actual_credits_cost` integer: Final credits charged after settlement (equals estimate today).
      - `webhook_url` string, uri
      - `api_key_id` string: The organization's API key that created the task; absent for dashboard/session-created tasks.
      - `created_at` integer, required: Unix seconds.
      - `queued_at` integer: Unix seconds.
      - `started_at` integer: Unix seconds.
      - `completed_at` integer: Unix seconds.
      - `expires_at` integer, required: Unix seconds; result + asset retention deadline.
    - `next_cursor` string, nullable, required: Cursor for the next page, or null when there are no more results.

## Other responses

- `400`: Standard error envelope returned by every error response (OpenAI-style).
- `401`: Standard error envelope returned by every error response (OpenAI-style).
- `429`: Standard error envelope returned by every error response (OpenAI-style).

---

[API](https://skmtc.dev/hotapi/apis/hotapi-gateway.md) · [All operations](https://skmtc.dev/hotapi/apis/hotapi-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/hotapi/apis/hotapi-gateway/revisions/9b6578b0c389?raw)