---
title: "Run"
method: POST
path: "/v2/rollouts/run"
tags: ["rollouts"]
---

# Run

`POST /v2/rollouts/run`

Launch a single hosted rollout and return its trace and job identifiers.

## Request body

- RolloutRunRequest — Single-trace launch.
  - `task_version_id` string, uuid, required
  - `model_id` string, uuid, required
  - `trace_id` string, uuid, nullable
  - `max_steps` integer
  - `trace_name` string, nullable
  - `runtime_config` SubmittedRuntimeConfig — SDK ``RuntimeConfig`` accepted by hosted v6 submissions. Provider-specific support is validated by the SDK runtime implementation.
    - `image` string, nullable
    - `compose` SubmittedComposeProject — Compose document and its optional environment source artifact.
      - `document` SubmittedComposeDocument, required — Normalized Compose document transported with a hosted runtime artifact.
        - `services` object, required
      - `root` SubmittedComposeProjectRef — Build-context location inside the selected environment source artifact.
        - `compose_path` string, required
      - `service_access` boolean, nullable
    - `resources` SubmittedRuntimeResources — Wire-compatible subset of ``hud.eval.runtime.RuntimeResources``.
      - `cpu` number, nullable
      - `memory_mb` integer, nullable
      - `storage_mb` integer, nullable
      - `gpu` SubmittedRuntimeGPU — Wire-compatible subset of ``hud.eval.runtime.RuntimeGPU``.
        - `type` string, nullable
        - `count` integer
    - `limits` SubmittedRuntimeLimits — Wire-compatible subset of ``hud.eval.runtime.RuntimeLimits``.
      - `startup_timeout_s` integer, nullable
      - `run_timeout_s` integer, nullable

## Response `201`

Successful Response

- RolloutResponse
  - `job_id` string, uuid, required
  - `trace_id` string, uuid, required
  - `status` string

## Other responses

- `400` — Invalid or malformed request
- `401` — Missing or invalid credentials
- `403` — Caller may not access this resource
- `404` — Referenced entity does not exist
- `409` — Resource already exists
- `422` — Validation Error

---

[API](https://skmtc.dev/hud/apis/hud-platform.md) · [All operations](https://skmtc.dev/hud/apis/hud-platform/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hud/hud-platform/revisions/58558fc733d9/schema)