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

# List your async tasks

`GET /v1/tasks`

## Request

- Base URL: `https://nanostudiopro.com/api`
- URL: `https://nanostudiopro.com/api/v1/tasks`
- Auth: HTTP bearer

Returns the authenticated user's tasks — uploads, scans, exports, and generations of every kind — with their lifecycle status. Useful for polling job state from external clients.

Every operation that creates server-side work has a Task row. POST endpoints like `/v1/generations` return a `task_id` you can pass to `/v1/tasks/{id}` for status updates.

## Query parameters

- `status` string
- `action` 'upload' | 'scan' | 'export' | 'generate'
- `kind` string
- `parent_task_id` string
- `since` string, date-time
- `completed_after` string, date-time
- `limit` integer

## Response `200`

List of tasks (most recently started first).

- object
  - `tasks` Task[]
    - `id` string
    - `action` 'upload' | 'scan' | 'export' | 'generate': High-level grouping of the operation.
    - `kind` string: Specific operation — e.g. `generate.quick`, `generate.restyle`, `generate.video`, `generate.angles`, `upload`, `scan`, `export`.
    - `status` 'queued' | 'running' | 'complete' | 'failed' | 'canceled'
    - `progress` integer: Best-effort 0-100; many endpoints leave it at 0.
    - `error` string, nullable: User-facing error message if `status=failed`.
    - `label` string, nullable
    - `origin` string, nullable: Where the task was triggered from. `API` for external callers, plus values like `Prompter`, `Card menu`, `Pose editor`.
    - `display_meta` object, nullable: Free-form metadata (aspect ratio, project id, thumbnail path) used by the UI placeholder. Safe for external clients to display verbatim.
    - `intent` object, nullable: Endpoint + body the task originated from. Used internally for retries.
    - `retries` integer: How many retry attempts have been made.
    - `max_retries` integer
    - `provider` object, nullable: External-system tracking for async providers (Kling video, future Runway/Pika/etc.). `null` for synchronous providers like Gemini.
      - `key` string
      - `task_id` string, nullable: External system's job id.
      - `status` string, nullable: Provider-specific status string.
      - `updated_at` string, date-time, nullable
    - `generation_id` string, nullable: FK to the resulting Generation, if applicable.
    - `asset_id` string, nullable: FK to the resulting Asset, if applicable.
    - `scan_result_id` string, nullable
    - `parent_task_id` string, nullable: For batched operations — points to the parent Task.
    - `started_at` string, date-time
    - `completed_at` string, date-time, nullable
    - `created_at` string, date-time

## Other responses

- `401`: Missing or invalid token
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/nanostudiopro/apis/nano-studio-pro-api.md) · [All operations](https://skmtc.dev/nanostudiopro/apis/nano-studio-pro-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nanostudiopro/apis/nano-studio-pro-api/revisions/b454211e598e?raw)