Runs

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"
    }
  ]
}

Getting Started

SDK

API Reference

Guides

Configuration

Start Run

Request Body

Response `201`

End Run

Request Body

Response `200`

Create Step

Request Body

Response `201`

Update Step

Request Body

Response `200`

List Runs

Query Parameters

Response `200`

Get Run Detail

Response `200`

​Start Run

​Request Body

​Response 201

​End Run

​Request Body

​Response 200

​Create Step

​Request Body

​Response 201

​Update Step

​Request Body

​Response 200

​List Runs

​Query Parameters

​Response 200

​Get Run Detail

​Response 200

Start Run

Request Body

Response `201`

End Run

Request Body

Response `200`

Create Step

Request Body

Response `201`

Update Step

Request Body

Response `200`

List Runs

Query Parameters

Response `200`

Get Run Detail

Response `200`