Runs

Start, end, and query guarded runs and their steps.

Start Run

This is the primary SDK entry point. The SDK calls this automatically when you use guard.run().

POST /v1/runs/

Starts a new guarded run. Evaluates all guardrails and returns an initial ALLOW/DENY decision.

Auth: API Key

Request Body

{
  "user_id": "alice",
  "metadata": { "agent": "support-bot" }
}

Field	Type	Required	Description
user_id	string	Yes	SDK user identifier
metadata	object | null	No	Arbitrary metadata attached to the run

Response 201

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "RUNNING",
  "decision": {
    "outcome": "ALLOW",
    "reason": null
  }
}

If denied:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "BLOCKED",
  "decision": {
    "outcome": "DENY",
    "reason": "KILL_SWITCH_ACTIVE"
  }
}

---

End Run

POST /v1/runs/{run_id}/end

Ends a run with a final status. Called automatically by the SDK when exiting the guard.run() context.

Auth: API Key

Request Body

{
  "status": "COMPLETED"
}

Field	Type	Required	Description
status	string	Yes	"COMPLETED" or "FAILED"

Response 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "COMPLETED",
  "ended_at": "2025-01-15T10:30:00Z"
}

---

Create Step

POST /v1/runs/{run_id}/steps

Creates a step within a run and evaluates guardrails. Called by the SDK before executing model_call() or tool_call().

Auth: API Key

Request Body

{
  "type": "MODEL_CALL",
  "sequence": 1,
  "model": "gpt-4o",
  "tool_name": null,
  "input_data": { "messages": [{ "role": "user", "content": "Hello" }] }
}

Field	Type	Required	Description
type	string	Yes	Step type: INPUT, MODEL_CALL, TOOL_CALL, OUTPUT, REASONING, SYSTEM
sequence	integer	Yes	Step order within the run (1-indexed)
model	string | null	No	Model identifier (for MODEL_CALL steps)
tool_name	string | null	No	Tool identifier (for TOOL_CALL steps)
input_data	object | null	No	Input payload for audit

Response 201

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "status": "ALLOWED",
  "decision": {
    "outcome": "ALLOW",
    "reason": null
  }
}

---

Update Step

PATCH /v1/runs/{run_id}/steps/{step_id}

Reports the result of a step after execution. Called by the SDK after fn() completes. Token counts trigger cost calculation.

Auth: API Key

Request Body

{
  "status": "COMPLETED",
  "duration_ms": 1200,
  "prompt_tokens": 500,
  "completion_tokens": 100
}

Field	Type	Required	Description
status	string	Yes	"COMPLETED" or "FAILED"
duration_ms	integer | null	No	Execution time in milliseconds
prompt_tokens	integer | null	No	Input tokens consumed
completion_tokens	integer | null	No	Output tokens consumed

Response 200

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "status": "COMPLETED"
}

---

List Runs

GET /v1/runs/

Lists runs with optional filtering and pagination.

Auth: JWT or API Key

Query Parameters

Parameter	Type	Default	Description
status	string | null	null	Filter by status: RUNNING, COMPLETED, FAILED, BLOCKED
user_id	string | null	null	Filter by SDK user ID
page	integer	1	Page number (1-indexed)
per_page	integer	50	Items per page (max 100)

Response 200

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "alice",
      "status": "COMPLETED",
      "started_at": "2025-01-15T10:00:00Z",
      "ended_at": "2025-01-15T10:30:00Z",
      "step_count": 3,
      "total_tokens": 1500,
      "total_cost_usd": 0.0045
    }
  ],
  "total": 142,
  "page": 1,
  "per_page": 50
}

---

Get Run Detail

GET /v1/runs/{run_id}

Returns the full run with its step timeline, tokens, and costs.

Auth: JWT or API Key

Response 200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "alice",
  "status": "COMPLETED",
  "metadata": { "agent": "support-bot" },
  "started_at": "2025-01-15T10:00:00Z",
  "ended_at": "2025-01-15T10:30:00Z",
  "total_tokens": 1500,
  "total_cost_usd": 0.0045,
  "duration_ms": 1800000,
  "steps": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "type": "MODEL_CALL",
      "status": "COMPLETED",
      "sequence": 1,
      "model": "gpt-4o",
      "tool_name": null,
      "prompt_tokens": 500,
      "completion_tokens": 100,
      "cost_usd": 0.00225,
      "duration_ms": 1200,
      "input_data": null,
      "output_data": null,
      "decision": {
        "outcome": "ALLOW",
        "reason": null
      },
      "created_at": "2025-01-15T10:00:01Z"
    }
  ]
}