Start Run
This is the primary SDK entry point. The SDK calls this automatically when you use guard.run().
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
}
}
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "BLOCKED",
"decision": {
"outcome": "DENY",
"reason": "KILL_SWITCH_ACTIVE"
}
}
End Run
POST /v1/runs/{run_id}/end
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
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}
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
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
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"
}
]
}
