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

# The Run object

> One conversation turn. Has a state, an optional assistant message, and a trace.

A run starts when you post a message. It ends `closed` or `failed`. In between it may pause for a question (`awaiting_input`) or a side-effect confirmation (`awaiting_outcome`).

```json theme={null}
{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "thread_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "state": "closed",
  "terminal": true,
  "cost_credits": 0.12,
  "connection": {
    "id": "2c5ea4c0-4067-11e9-8bad-9b1deb4d3b7d",
    "name": "production"
  },
  "message": {
    "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "role": "assistant",
    "content": "Sent. Reference NIP-4419.",
    "created_at": "2026-08-16T12:00:04Z"
  }
}
```

## Attributes

<ResponseField name="id" type="uuid" required>
  Unique identifier for the run.
</ResponseField>

<ResponseField name="thread_id" type="uuid">
  Thread this turn belongs to.
</ResponseField>

<ResponseField name="state" type="enum" required>
  `running`, `awaiting_input`, `awaiting_outcome`, `closed`, or `failed`.
</ResponseField>

<ResponseField name="terminal" type="boolean">
  `true` when the run will not change again (`closed` or `failed`).
</ResponseField>

<ResponseField name="cost_credits" type="number">
  Credits charged for this run.
</ResponseField>

<ResponseField name="connection" type="object">
  Host used for customer tools, when one was resolved.

  <Expandable title="properties">
    <ResponseField name="id" type="uuid">
      Connection id.
    </ResponseField>

    <ResponseField name="name" type="string">
      Connection name.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="message" type="object">
  Latest assistant message, when the run has one.
</ResponseField>

## Trace

`GET /v1/loom/runs/:id/trace` returns the same run plus the ordered turns. This is what "every run on a trace" means.

<ResponseField name="opened_at" type="timestamp">
  When the run started.
</ResponseField>

<ResponseField name="closed_at" type="timestamp">
  When the run reached a terminal state.
</ResponseField>

<ResponseField name="turns" type="array">
  Model turns in order.

  <Expandable title="turn">
    <ResponseField name="seq" type="integer">
      Turn index.
    </ResponseField>

    <ResponseField name="model_class" type="string">
      Model class used for this turn.
    </ResponseField>

    <ResponseField name="input_tokens" type="integer">
      Prompt tokens.
    </ResponseField>

    <ResponseField name="output_tokens" type="integer">
      Completion tokens.
    </ResponseField>

    <ResponseField name="cost_credits" type="number">
      Credits for this turn.
    </ResponseField>

    <ResponseField name="request" type="object">
      Model request payload.
    </ResponseField>

    <ResponseField name="response" type="object">
      Model response payload.
    </ResponseField>

    <ResponseField name="tool_calls" type="array">
      Tools invoked during the turn — `patch_ref`, `interaction`, `status`, `args`, `result`, `risk`, `reliability`, `cost_credits`, and an `outcome` when one was recorded.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="requests" type="array">
  Data-plane HTTP calls attributed to this run (identify, and so on), newest first.
</ResponseField>

<ResponseField name="requests_count" type="integer">
  Total attributed requests, which may exceed the array length.
</ResponseField>

## Outcomes

When `state` is `awaiting_outcome`, post `{ tool_call_id, state }` where `state` is `occurred` or `failed`. Optional `detail` is stored on the outcome. A retry against an already-resolved tool call is a no-op.

## Endpoints

* [Retrieve a run](/api-reference/loom/retrieve-a-run) — `GET /v1/loom/runs/:id`
* [Retrieve a run trace](/api-reference/loom/retrieve-a-run-trace) — `GET /v1/loom/runs/:id/trace`
* [Resolve an outcome](/api-reference/loom/resolve-an-outcome) — `POST /v1/loom/runs/:run_id/outcome`