Runs API

Runs execute workflow.v0 specs - multi-step workflows with parallel LLM calls, data transformations, and tool execution. Each run produces an append-only event stream and aggregated outputs.

Quick Reference

POST   /api/v1/runs                      Create a run
GET    /api/v1/runs/:id                  Get run status and outputs
GET    /api/v1/runs/:id/events           Stream run events
GET    /api/v1/runs/:id/pending-tools    Get pending tool calls
POST   /api/v1/runs/:id/tool-results     Submit tool results

Authentication

All run endpoints accept:

• Secret key (mr_sk_*): Backend use with full project access
• Customer bearer token: Customer scoped token for data-plane access

Publishable keys (mr_pk_*) cannot call run endpoints directly.

Create Run

POST /api/v1/runs

Starts a workflow run and returns a run_id. The run executes asynchronously - use the events endpoint to stream progress.

Request Body

Response

Example

curl -X POST https://api.modelrelay.ai/api/v1/runs \
  -H "Authorization: Bearer mr_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "kind": "workflow.v0",
      "name": "parallel-analysis",
      "nodes": [
        {
          "id": "summarize",
          "type": "llm.responses",
          "input": {
            "model": "claude-sonnet-4-20250514",
            "input": [
              {"type": "message", "role": "user", "content": [{"type": "text", "text": "Summarize: AI is transforming software development."}]}
            ]
          }
        },
        {
          "id": "critique",
          "type": "llm.responses",
          "input": {
            "model": "claude-sonnet-4-20250514",
            "input": [
              {"type": "message", "role": "user", "content": [{"type": "text", "text": "Critique: AI is transforming software development."}]}
            ]
          }
        }
      ],
      "outputs": [
        {"name": "summary", "from": "summarize"},
        {"name": "critique", "from": "critique"}
      ]
    }
  }'

const run = await mr.runs.create({
  spec: {
    kind: "workflow.v0",
    name: "parallel-analysis",
    nodes: [
      {
        id: "summarize",
        type: "llm.responses",
        input: {
          model: "claude-sonnet-4-20250514",
          input: [
            { type: "message", role: "user", content: [{ type: "text", text: "Summarize: AI is transforming software development." }] }
          ]
        }
      },
      {
        id: "critique",
        type: "llm.responses",
        input: {
          model: "claude-sonnet-4-20250514",
          input: [
            { type: "message", role: "user", content: [{ type: "text", text: "Critique: AI is transforming software development." }] }
          ]
        }
      }
    ],
    outputs: [
      { name: "summary", from: "summarize" },
      { name: "critique", from: "critique" }
    ]
  }
});

console.log(`Run started: ${run.run_id}`);

run, err := client.Runs.Create(ctx, sdk.RunsCreateRequest{
    Spec: map[string]any{
        "kind": "workflow.v0",
        "name": "parallel-analysis",
        "nodes": []map[string]any{
            {
                "id":   "summarize",
                "type": "llm.responses",
                "input": map[string]any{
                    "model": "claude-sonnet-4-20250514",
                    "input": []map[string]any{
                        {"type": "message", "role": "user", "content": []map[string]any{
                            {"type": "text", "text": "Summarize: AI is transforming software development."},
                        }},
                    },
                },
            },
        },
        "outputs": []map[string]any{
            {"name": "summary", "from": "summarize"},
        },
    },
})

Response

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "plan_hash": "abc123def456"
}

Get Run

GET /api/v1/runs/:id

Returns the current run snapshot including status, node results, outputs, and cost summary.

Response

Example

curl https://api.modelrelay.ai/api/v1/runs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer mr_sk_..."

const run = await mr.runs.get("550e8400-e29b-41d4-a716-446655440000");

if (run.status === "succeeded") {
  console.log("Outputs:", run.outputs);
  console.log(`Total cost: $${run.cost_summary.total_usd_cents / 100}`);
}

Response

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "succeeded",
  "plan_hash": "abc123def456",
  "cost_summary": {
    "total_usd_cents": 5,
    "line_items": [
      {"node_id": "summarize", "model": "claude-sonnet-4-20250514", "usd_cents": 3},
      {"node_id": "critique", "model": "claude-sonnet-4-20250514", "usd_cents": 2}
    ]
  },
  "nodes": [
    {"id": "summarize", "type": "llm.responses", "status": "succeeded"},
    {"id": "critique", "type": "llm.responses", "status": "succeeded"}
  ],
  "outputs": {
    "summary": {"type": "message", "role": "assistant", "content": [...]},
    "critique": {"type": "message", "role": "assistant", "content": [...]}
  }
}

Stream Events

GET /api/v1/runs/:id/events

Streams the append-only event history for a run. Events are ordered by sequence number (seq) and can be resumed using after_seq.

Query Parameters

Headers

Example

# Stream all events (NDJSON)
curl https://api.modelrelay.ai/api/v1/runs/550e8400-e29b-41d4-a716-446655440000/events \
  -H "Authorization: Bearer mr_sk_..." \
  -H "Accept: application/x-ndjson"

# Resume from sequence 10
curl "https://api.modelrelay.ai/api/v1/runs/550e8400-e29b-41d4-a716-446655440000/events?after_seq=10" \
  -H "Authorization: Bearer mr_sk_..." \
  -H "Accept: application/x-ndjson"

const stream = await mr.runs.events("550e8400-e29b-41d4-a716-446655440000");

for await (const event of stream) {
  console.log(`[${event.seq}] ${event.type}`);

  if (event.type === "node_output_delta" && event.delta?.text_delta) {
    process.stdout.write(event.delta.text_delta);
  }

  if (event.type === "run_completed") {
    console.log("Run finished!");
    break;
  }
}

Event Stream

{"envelope_version":"v0","run_id":"...","seq":1,"ts":"...","type":"run_compiled"}
{"envelope_version":"v0","run_id":"...","seq":2,"ts":"...","type":"run_started","plan_hash":"abc123"}
{"envelope_version":"v0","run_id":"...","seq":3,"ts":"...","type":"node_started","node_id":"summarize"}
{"envelope_version":"v0","run_id":"...","seq":4,"ts":"...","type":"node_output_delta","node_id":"summarize","delta":{"kind":"message_delta","text_delta":"AI"}}
{"envelope_version":"v0","run_id":"...","seq":5,"ts":"...","type":"node_succeeded","node_id":"summarize"}
{"envelope_version":"v0","run_id":"...","seq":6,"ts":"...","type":"run_completed"}

Get Pending Tools

GET /api/v1/runs/:id/pending-tools

Returns pending tool calls for runs using client-side tool execution mode. When a node emits a node_waiting event, use this endpoint to retrieve the tool calls that need execution.

Response

Pending Node Object

Example

curl https://api.modelrelay.ai/api/v1/runs/550e8400-e29b-41d4-a716-446655440000/pending-tools \
  -H "Authorization: Bearer mr_sk_..."

Response

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "pending": [
    {
      "node_id": "agent",
      "step": 2,
      "request_id": "req_abc123",
      "tool_calls": [
        {
          "tool_call_id": "call_xyz789",
          "name": "get_weather",
          "arguments": "{\"location\": \"London\"}"
        }
      ]
    }
  ]
}

Submit Tool Results

POST /api/v1/runs/:id/tool-results

Submits tool execution results to resume a waiting run. Use the values from /pending-tools to correlate the results.

Request Body

Tool Result Object

Example

curl -X POST https://api.modelrelay.ai/api/v1/runs/550e8400-e29b-41d4-a716-446655440000/tool-results \
  -H "Authorization: Bearer mr_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": "agent",
    "step": 2,
    "request_id": "req_abc123",
    "results": [
      {
        "tool_call_id": "call_xyz789",
        "name": "get_weather",
        "output": "{\"temperature\": 18, \"condition\": \"cloudy\"}"
      }
    ]
  }'

Response

{
  "accepted": 1,
  "status": "running"
}

Run Status

Runs transition through these states:

State Machine

stateDiagram-v2
    [*] --> running
    running --> waiting
    running --> succeeded
    running --> failed
    waiting --> running: tool results submitted

Node Status

Individual nodes have their own status:

Event Types

Run Lifecycle Events

Node Events

LLM Events

Event Envelope

All events share this envelope structure:

Node Types

llm.responses

Executes an LLM request using the /responses API. Supports streaming, tools, and structured output.

{
  "id": "summarize",
  "type": "llm.responses",
  "input": {
    "model": "claude-sonnet-4-20250514",
    "input": [...],
    "tools": [...],
    "output_format": {...}
  }
}

join.all

Waits for all upstream nodes to complete before proceeding. Used for synchronization points.

{
  "id": "sync",
  "type": "join.all"
}

transform.json

Transforms node outputs using JSON Pointer extraction.

{
  "id": "extract",
  "type": "transform.json",
  "input": {
    "from": "upstream_node",
    "pointer": "/content/0/text"
  }
}

Tool Execution Modes

Server-Side (default)

Tools are executed by the server automatically. The run continues without client interaction.

Client-Side

Tools are sent to the client for execution. The run pauses (waiting status) until results are submitted via /tool-results.

Configure per-node:

{
  "id": "agent",
  "type": "llm.responses",
  "input": {
    "model": "claude-sonnet-4-20250514",
    "input": [...],
    "tools": [...],
    "tool_execution": {
      "mode": "client"
    }
  }
}

Error Codes

Next Steps

• Responses API - Single LLM requests
• Workflow Spec Reference - Full workflow.v0 schema