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).

{
  "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

id · uuid · required

Unique identifier for the run.

thread_id · uuid

Thread this turn belongs to.

state · enum · required

running, awaiting_input, awaiting_outcome, closed, or failed.

terminal · boolean

true when the run will not change again (closed or failed).

cost_credits · number

Credits charged for this run.

connection · object

Host used for customer tools, when one was resolved.

Show properties

id · uuid

Connection id.

name · string

Connection name.

message · object

Latest assistant message, when the run has one.

Trace

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

opened_at · timestamp

When the run started.

closed_at · timestamp

When the run reached a terminal state.

turns · array

Model turns in order.

Show turn

seq · integer

Turn index.

model_class · string

Model class used for this turn.

input_tokens · integer

Prompt tokens.

output_tokens · integer

Completion tokens.

cost_credits · number

Credits for this turn.

request · object

Model request payload.

response · object

Model response payload.

tool_calls · array

Tools invoked during the turn — patch_ref, interaction, status, args, result, risk, reliability, cost_credits, and an outcome when one was recorded.

requests · array

Data-plane HTTP calls attributed to this run (identify, and so on), newest first.

requests_count · integer

Total attributed requests, which may exceed the array length.

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 — GET /v1/loom/runs/:id
• Retrieve a run trace — GET /v1/loom/runs/:id/trace
• Resolve an outcome — POST /v1/loom/runs/:run_id/outcome