> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pikarc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Runs

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

## Start Run

<Note>This is the primary SDK entry point. The SDK calls this automatically when you use `guard.run()`.</Note>

```
POST /v1/runs/
```

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

**Auth**: API Key

### Request Body

```json theme={null}
{
  "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`

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

If denied:

```json theme={null}
{
  "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

```json theme={null}
{
  "status": "COMPLETED"
}
```

| Field    | Type     | Required | Description                 |
| -------- | -------- | -------- | --------------------------- |
| `status` | `string` | Yes      | `"COMPLETED"` or `"FAILED"` |

### Response `200`

```json theme={null}
{
  "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

```json theme={null}
{
  "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`

```json theme={null}
{
  "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

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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"
    }
  ]
}
```