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

# Tasks

> Reference for task endpoints, statuses, and result retrieval.

Mynth tasks represent asynchronous work. Image generation, content rating, and alt text requests all create tasks.

Task types:

* `image.generate`
* `image.rate`
* `image.alt`

## Status values

* `pending`
* `completed`
* `failed`

## Endpoints

### `GET /tasks/:id`

Returns the full task object.

Authentication:

* requires your Mynth API key
* owner-only
* Public Access Tokens do not work here

### `GET /tasks/:id/status`

Returns only:

```json theme={"theme":"kanagawa-dragon"}
{
  "data": {
    "status": "pending"
  }
}
```

Authentication:

* API key, or
* task-scoped Public Access Token

### `GET /tasks/:id/result`

Returns:

```json theme={"theme":"kanagawa-dragon"}
{
  "data": {
    "id": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
    "status": "completed",
    "type": "image.generate",
    "result": {
      "model": "google/gemini-3.1-flash-image",
      "images": [
        {
          "status": "success",
          "id": "img_123",
          "url": "https://...",
          "mynth_url": "https://...",
          "cost": "0.01250000",
          "size": "1024x1024"
        }
      ]
    }
  }
}
```

Authentication:

* API key, or
* task-scoped Public Access Token

## Full task shape

`GET /tasks/:id` returns the complete task object:

```json theme={"theme":"kanagawa-dragon"}
{
  "data": {
    "id": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
    "status": "completed",
    "type": "image.generate",
    "cost": "0.01250000",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:12.000Z",
    "request": {
      "prompt": "Editorial product photo of a ceramic mug",
      "model": "google/gemini-3.1-flash-image",
      "size": "landscape",
      "count": 1
    },
    "result": {
      "model": "google/gemini-3.1-flash-image",
      "images": [
        {
          "status": "success",
          "id": "img_123",
          "url": "https://...",
          "mynth_url": "https://...",
          "cost": "0.01250000",
          "size": "1536x1024"
        }
      ]
    }
  }
}
```

Fields:

* `request` contains the original task parameters as submitted.
* `result` contains task-specific output. It is `null` for `pending` tasks and for failed tasks that did not produce a result.
* For `image.generate`, `result` contains the resolved `model`, `images`, and optional `magic_prompt`.
* For `image.rate`, `result.results` contains per-URL rating items.
* For `image.alt`, `result.results` contains per-URL alt text items.
* `result.magic_prompt` is present when `magic_prompt: true` was applied, containing the enhanced `positive` and optional `negative` prompt.
* `cost` at the task level is the total cost as a decimal string. Per-image cost is returned on each image in `result.images[].cost`.
* When `size: "auto"` is used, the selected dimensions are reflected in each image's `size` field (`{width}x{height}`).
* `errors` is present on `failed` tasks as an array of `{ code }`.

## Result image states

Each image result is either:

* `success`
* `failed`

A successful image includes `id`, `url` (nullable when delivered only to a destination), `mynth_url`, `size` (`{width}x{height}`), and `cost` (per-image decimal string). A failed image includes `error.code`.

If you want only successful image URLs in the SDK, use `task.urls` or `task.getImages()`.