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

# Runs

> Submit, monitor, retrieve, and cancel model inference runs.

A run is one model inference request. Submission reserves the quoted credits
and returns a run ID immediately.

## Lifecycle

A run moves through these states:

* `queued`: accepted and waiting to start.
* `running`: generation is in progress.
* `completed`: output is ready.
* `failed`: generation failed and the reservation was released.
* `canceled`: canceled by the caller.

## Submit

Send a flat JSON body to `POST /v1/run/{model_id}`. The model entry defines
which fields the body accepts.

```sh theme={null}
curl -X POST https://api.protoface.com/v1/run/minimax-h3 \
  -H "Authorization: Bearer $PROTOFACE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-shot-001" \
  -d '{
    "prompt": "A slow camera move around a ceramic lamp in a quiet studio.",
    "duration_seconds": 8,
    "quality": "768p",
    "aspect_ratio": "16:9"
  }'
```

Use an `Idempotency-Key` when a request may be retried. Reusing the key with the
same request returns the original run. Reusing it with a different request
returns a conflict.

## Media inputs

Models that accept images, video, or audio can take:

* An `asset_...` ID returned by `POST /v1/assets` or a previous run.
* A public HTTPS URL.
* A data URI.

Use a URL or data URI for one-off input. Use an asset ID to reuse media across
runs.

The field names and maximum number of files vary by model. Check
`GET /v1/models/{model_id}` before building the request.

## Poll status

Use the lightweight status endpoint while the run is active:

```sh theme={null}
curl https://api.protoface.com/v1/runs/run_.../status \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"
```

Wait between polls. `queue_position` is available while a run is queued and may
be `null` after it starts.

## Retrieve a result

```sh theme={null}
curl https://api.protoface.com/v1/runs/run_... \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"
```

The `outputs` array contains the full result. When there is exactly one video
output, the response also includes it in `video` for convenience.

## Cancel

```sh theme={null}
curl -X POST https://api.protoface.com/v1/runs/run_.../cancel \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"
```

Canceling a queued run releases all reserved credits. Once a run starts,
canceling it still charges the full reserved amount. Completed and failed runs
return `409` if you try to cancel them.

## List runs and events

List recent runs:

```sh theme={null}
curl "https://api.protoface.com/v1/runs?limit=20" \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"
```

For detailed progress or debugging, read the ordered event stream:

```sh theme={null}
curl https://api.protoface.com/v1/runs/run_.../events \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"
```

## Next

<Columns cols={2}>
  <Card title="Models" href="/guides/models" icon="boxes">
    Read model capabilities and request fields.
  </Card>

  <Card title="Errors" href="/reference/errors" icon="triangle-alert">
    Handle rate limits, conflicts, and failed requests.
  </Card>
</Columns>