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

# carrothub status

> Query the status of an async task, optionally polling to completion

`status` checks on a task that was previously submitted with
[`carrothub run --no-wait`](https://www.carrothub.ai/docs/cli/commands/run) (or via the HTTP API directly).
It can either return the current snapshot or block and poll until the task
reaches a terminal state.

## Synopsis

```bash theme={null}
carrothub status <api-path> <task-id> [options]
```

## Arguments

| Argument | Description |
| - | - |
| `<api-path>` | The task path printed by `run --no-wait`, e.g. `/vendors/alibaba/v1/wan2.6-t2v/generation`. Also shown as `api_path` in `carrothub list --json` and as **API Path** in `carrothub params`. |
| `<task-id>` | The task UUID returned when the task was created. |

The CLI builds the actual poll URL as `<base-url><api-path>/<task-id>`.

## Options

| Option | Default | Description |
| - | - | - |
| `--api-key <key>` | env | Override API key |
| `--base-url <url>` | env | Override base URL |
| `--site <site>` | env | Override site |
| `--wait` | — | Poll until the task completes instead of returning immediately |
| `--poll-interval <s>` | `20` | Polling interval in seconds (used with `--wait`) |
| `--max-wait <s>` | `900` | Maximum wait time in seconds (15 min) |
| `--quiet` | — | Suppress progress lines |
| `--json` | — | Machine-readable output |

## Examples

```bash theme={null}
# Snapshot — one request, then exit
carrothub status /vendors/alibaba/v1/wan2.6-t2v/generation 9d2b8c1a-...

# Block until done
carrothub status /vendors/alibaba/v1/wan2.6-t2v/generation 9d2b8c1a-... --wait

# JSON snapshot
carrothub status /vendors/alibaba/v1/wan2.6-t2v/generation 9d2b8c1a-... --json

# Custom polling cadence
carrothub status /vendors/alibaba/v1/wan2.6-t2v/generation 9d2b8c1a-... \
  --wait --poll-interval 10 --max-wait 1800
```

## Output

### Text

```
Task ID: 9d2b8c1a-...
Status:  succeeded

Results:
  https://cdn.carrothub.ai/.../video-0.mp4
```

Status is color-coded:

| Status | Color |
| - | - |
| `succeeded`, `completed` | green |
| `pending`, `queued`, `running`, `processing` | yellow |
| `failed` and other terminal failures | red |

### JSON

```json theme={null}
{
  "task_id": "9d2b8c1a-...",
  "status": "succeeded",
  "results": ["https://cdn.carrothub.ai/.../video-0.mp4"]
}
```

When the task failed, an `error` field is included.

## Async workflow

```bash theme={null}
# Step 1 — kick off
RESPONSE=$(carrothub run alibaba/wan2.6-t2v \
  --prompt "A long cinematic shot" --no-wait --json)

TASK_ID=$(echo "$RESPONSE" | jq -r '.task_id')
API_PATH=$(echo "$RESPONSE" | jq -r '.api_path')

# Step 2 — wait somewhere else (different shell, later in CI, ...)
carrothub status "$API_PATH" "$TASK_ID" --wait --json > result.json
```

See [Async tasks](https://www.carrothub.ai/docs/cli/workflows/async-tasks.md) for fuller patterns.

## Exit codes

| Code | Meaning |
| - | - |
| `0` | Task is in a success state (`succeeded` / `completed`) |
| `1` | Task failed, or any transport / config error |

Pending and running statuses return `0` for snapshot calls (without `--wait`)
because they are not failures — they just aren't done yet. With `--wait`, the
exit code reflects the terminal status.


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