# List runs

GET https://fusara.ai/api/v3/run

Accepted v3 runs belonging to the authenticated API owner, across their API keys. Fixed pages of up to 100 runs ordered by created_at descending, then id descending. Follow next (older) or previous (newer) URLs unchanged with API authentication; unavailable links are omitted. Cursors retain filters, expire 24 hours after the first page, and exclude new head entries; statuses, costs and availability remain live. Invalid/foreign cursors return 422 invalid_cursor, expired cursors return 410 cursor_expired. Empty history returns data: []. List outputs are descriptors with usable media URLs and expiry, without large inline text/JSON; GET /api/v3/run/{id} returns full results.

## Example request

```bash
curl 'https://fusara.ai/api/v3/run?status=succeeded&model=qwen-image21-create' \
  -H "Authorization: Bearer $FUSARA_API_KEY"
```

## Parameters

- `model` (string): Exact public model ID, including its variant. Historical disabled models remain searchable. query.
- `status` (string): Distinct comma-separated statuses: queued, running, succeeded, failed, canceled. Values are OR; different filters are AND. query.
- `created_from` (string): Inclusive RFC 3339 creation timestamp with an explicit timezone (up to seven fractional digits). query.
- `created_to` (string): Exclusive RFC 3339 creation timestamp. Must be later than created_from. query.
- `ids` (string): Up to 100 distinct positive run IDs, comma-separated. Only accessible matches are returned, newest first. query.
- `cursor` (string): Opaque continuation token from a returned link. Cannot be combined with other query parameters. query.

## Responses

### 200

OK

#### Response headers

- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

```json
{
  "data": [
    {
      "id": 123456,
      "status": "succeeded",
      "cost": {
        "unit": "common_fuz",
        "expected": "40.0000",
        "status": "settled",
        "charged": "40.0000"
      },
      "outputs": [
        {
          "type": "image",
          "media_id": 901,
          "url": "https://media.example/result.png",
          "url_expires_at": "2026-10-25T12:00:00Z"
        }
      ],
      "model": "qwen-image21-create",
      "created_at": "2026-10-24T12:00:00Z"
    }
  ]
}
```

#### Response body

- `data` (object[], required): Up to 100 accepted v3 runs, newest first. An empty history is an empty array.
- `data.id` (integer, required) Format: int64; Minimum: 0; Maximum: 4294967295.
- `data.model` (string, required)
- `data.status` (string, required)
- `data.created_at` (string, required) Format: date-time.
- `data.cost` (object, required)
- `data.cost.unit` (string, required): Billing unit: common_fuz.
- `data.cost.expected` (string, required): Total accepted estimate for this run, as a decimal string.
- `data.cost.status` (string, required): pending until billing is confirmed, then settled. Generation can finish before settlement.
- `data.cost.charged` (string): Confirmed final charge, as a decimal string. Omitted while pending; confirmed zero is 0.0000.
- `data.outputs` (object[])
- `data.outputs.type` (string, required)
- `data.outputs.media_id` (integer): Reusable account media ID when this output is a file. Format: int64; Minimum: 0; Maximum: 4294967295.
- `data.outputs.url` (string): Download URL when the file is available. Save it before url_expires_at.
- `data.outputs.url_expires_at` (string): UTC expiry of this output URL, when provided. Format: date-time.
- `data.outputs.expired` (boolean): True when the media is no longer available; its dead URL is omitted.
- `data.outputs.model_asset_id` (integer) Format: int64; Minimum: 0; Maximum: 4294967295.
- `data.error` (object)
- `data.error.code` (string, required): Machine-readable generation failure code.
- `data.error.message` (string, required): Human-readable explanation of the generation failure.
- `next` (string): Absolute URL for older matches. Follow unchanged with API authentication. Omitted at the end.
- `previous` (string): Absolute URL for newer matches. Follow unchanged with API authentication. Omitted when unavailable.

### 400

invalid_header: supply only one authentication header, Authorization: Bearer or X-API-Key.

#### Response headers

- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.

### 401

authentication_required: the API key is missing or invalid. Public methods allow omission, but reject invalid supplied credentials.

#### Response headers

- `WWW-Authenticate` (string, required): Bearer authentication challenge. Values: "Bearer".
- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.

### 410

cursor_expired: restart history from the initial request with its original filters.

#### Response headers

- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.

### 422

validation_error: correct the fields identified by error.errors[].pointer; unknown fields and query parameters are rejected. invalid_cursor: use a continuation token from this account's history links, without adding other filters.

#### Response headers

- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.

### 429

rate_limited (retryable: true): wait for the indicated delay, then retry. Use bounded backoff if no delay is supplied.

#### Response headers

- `Retry-After` (integer): When supplied, the minimum number of seconds to wait before retrying a transient failure. Preserve the original idempotency key and body when retrying a submission. Minimum: 1.
- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.

### 500

internal_error: unexpected server failure. Contact support if the failure persists; inspect error.retryable before retrying automatically.

#### Response headers

- `X-Request-Id` (string, required): Support/trace identifier for this HTTP request.

#### Response body

- `error` (object, required)
- `error.code` (string, required): Machine-readable request error code.
- `error.message` (string, required): Human-readable explanation.
- `error.retryable` (boolean, required): Whether the failure is transient. For uncertain POST outcomes, preserve the original idempotency key and body.
- `error.errors` (object[]): Field errors when applicable. Omitted otherwise.
- `error.errors.pointer` (string, required): JSON Pointer to the invalid field, such as /images/0/url.
- `error.errors.code` (string, required): Machine-readable field error code.
- `error.errors.message` (string, required): How this field failed validation.