---
title: "Start an RL example in one request"
method: POST
path: "/v1/rl-environments/{environment}/examples/{example}/runs"
tags: ["RL"]
---

# Start an RL example in one request

`POST /v1/rl-environments/{environment}/examples/{example}/runs`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/v1/rl-environments/{environment}/examples/{example}/runs`
- Auth: HTTP bearer

Submits the run the example describes: its command through a shell, its runtime image, a GPU with at least peak_memory_gb, its result files and its RL details with example_id. A retry is matched by environment, example and name under the Idempotency-Key, so it returns the original run even if the catalog changed in between. Omitting name means the example's default name. The same key with a different example or name returns 409. It is an ordinary workload. Follow it with GET /v1/workloads/{id}, its RL events and its outputs. 404 means no runnable example has these ids. Admission, spending checks and errors are those of POST /v1/workloads.

## Path parameters

- `environment` string, required
- `example` string, required

## Headers

- `Idempotency-Key` string, required

## Request body

- object
  - `name` string: Run name. Defaults to the environment and example names.

## Response `202`

Success

- SubmitResult
  - `id` string, required
  - `workload_id` string, required
  - `status` string, required
  - `revision` integer, required

## Other responses

- `default`: Error. The JSON error and message fields are stable. Additional fields may provide details. Authentication, rate limits, and transient failures apply to all operations.

## Changes

- **2026-10-01** `ba84c74aeec8`: 1 info
  - endpoint added
- **2026-10-01** `544fef290a54`: 1 breaking
  - api path removed without deprecation
- **2026-09-28** `7ff9649958d7`: 1 info
  - endpoint added
- **2026-09-28** `12e777b060de`: 1 breaking
  - api path removed without deprecation
- **2026-09-27** `adfc946d141d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/changes/v1/rl-environments/:environment/examples/:example/runs/post.md)

---

[API](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api.md) - [All operations](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/revisions/a59210899d95?raw)