---
title: "Post a finished automation run's record"
method: POST
path: "/code/runtime/runs"
---

# Post a finished automation run's record

`POST /code/runtime/runs`

## Request

- Base URL: `https://api.caveman.so/api/v1`
- URL: `https://api.caveman.so/api/v1/code/runtime/runs`
- Auth: HTTP bearer

POST /api/v1/code/runtime/runs on the Caveman Cloud control plane. Requires a Caveman Code runtime token (Authorization: Bearer ccrt_...), minted by POST /code/runtimes/{runtimeId}/token. Not exposed to autonomous agents: Not RBAC-guarded — authenticated by a Caveman Code runtime token, and only for an org workload's session on that runtime's computer: an automation run's record when it ends, an Agents API or automation session's spans (ADR 0134). Agents authenticate through a scoped control-plane session and never touch these directly.

## Request body

- object
  - `session_id` string, uuid, required
  - `automation_id` string, uuid, required
  - `record` object, required: The run record as journalled (SEMANTICS 12).

## Response `200`

Accepted

- object
  - `run_id` string, uuid, required
  - `ended` boolean, required
  - `replayed` boolean, required
  - `attempts` integer, required
  - `cost_usd` number, required

## Other responses

- `401`: A runtime token is required.
- `403`: Not an automation's session (cave_code_session_personal).
- `404`: Not a run of this session's automation.
- `409`: The session is on another computer, or the run already has a different record.
- `503`: The run ended but its step detail was not stored; send the same record again.
- `2XX`: Successful response. Exact status depends on synchronous or durable delivery outcome.
- `4XX`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `5XX`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.

---

[API](https://skmtc.dev/caveman/apis/caveman-cloud-api.md) - [All operations](https://skmtc.dev/caveman/apis/caveman-cloud-api/llms.txt) - [OpenAPI document](https://skmtc.dev/caveman/apis/caveman-cloud-api/revisions/508312d01cfc?raw)