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

# Processes

> Monitor and control running processes

## Overview

Processes represent the actual execution of attempts. Monitor running AI agents, check resource usage, and control execution.

**Base URL**: `http://localhost:8887/api/processes`

***

## List Processes

Get all active processes.

```http theme={null}
GET /api/processes
```

### Query Parameters

| Parameter | Type   | Description                                   |
| --------- | ------ | --------------------------------------------- |
| `status`  | enum   | Filter by status (running, completed, failed) |
| `llm`     | string | Filter by AI agent                            |

<RequestExample>
  ```bash cURL theme={null}
  curl http://localhost:8887/api/processes?status=running
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://localhost:8887/api/processes?status=running');
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get('http://localhost:8887/api/processes?status=running')
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "proc_abc123",
        "attemptId": "attempt_xyz789",
        "taskId": "task_def456",
        "llm": "claude",
        "status": "running",
        "startedAt": "2024-01-15T10:30:00Z",
        "duration": 45000,
        "resources": {
          "cpuUsage": 45.2,
          "memoryUsage": 512000000,
          "diskIO": 1024000
        },
        "progress": {
          "current": "Generating authentication logic",
          "percentage": 65
        }
      }
    ]
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "success": false,
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Authentication required"
    }
  }
  ```
</ResponseExample>

***

## Get Process

Get detailed process information.

```http theme={null}
GET /api/processes/:id
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "proc_abc123",
    "attemptId": "attempt_xyz789",
    "taskId": "task_def456",
    "llm": "claude",
    "model": "claude-3-5-sonnet-20241022",
    "status": "running",
    "startedAt": "2024-01-15T10:30:00Z",
    "duration": 45000,
    "resources": {
      "cpuUsage": 45.2,
      "memoryUsage": 512000000,
      "diskIO": 1024000,
      "networkIO": 204800
    },
    "progress": {
      "stage": "code_generation",
      "current": "Generating authentication logic",
      "percentage": 65,
      "estimatedRemaining": 25000
    },
    "tokens": {
      "inputTokens": 8420,
      "outputTokens": 1250,
      "estimatedCost": 0.12
    }
  }
}
```

***

## Cancel Process

Stop a running process.

```http theme={null}
POST /api/processes/:id/cancel
```

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST http://localhost:8887/api/processes/proc_abc123/cancel
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://localhost:8887/api/processes/proc_abc123/cancel', { method: 'POST' });
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'http://localhost:8887/api/processes/proc_abc123/cancel',
      json={...}
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "data": {
      "id": "proc_abc123",
      "status": "cancelled",
      "cancelledAt": "2024-01-15T10:32:00Z"
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "success": false,
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Authentication required"
    }
  }
  ```
</ResponseExample>

***

## Get Process Logs

Stream real-time logs from a process.

```http theme={null}
GET /api/processes/:id/logs
```

### Query Parameters

| Parameter | Type    | Description                    |
| --------- | ------- | ------------------------------ |
| `follow`  | boolean | Stream logs in real-time       |
| `tail`    | integer | Number of recent lines to show |

<RequestExample>
  ```bash cURL theme={null}
  curl "http://localhost:8887/api/processes/proc_abc123/logs?follow=true"
  ```

  ***

  ## Get Process Metrics

  Get resource usage metrics.

  ```http theme={null}
  GET /api/processes/:id/metrics
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://localhost:8887/api/processes/proc_abc123/logs?follow=true');
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get('http://localhost:8887/api/processes/proc_abc123/logs?follow=true')
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "data": {
      "processId": "proc_abc123",
      "metrics": [
        {
          "timestamp": "2024-01-15T10:30:00Z",
          "cpu": 45.2,
          "memory": 512000000,
          "diskIO": 1024000,
          "networkIO": 204800
        },
        {
          "timestamp": "2024-01-15T10:30:01Z",
          "cpu": 48.5,
          "memory": 524000000,
          "diskIO": 1126400,
          "networkIO": 225280
        }
      ],
      "averages": {
        "cpu": 46.8,
        "memory": 518000000
      }
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "success": false,
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Authentication required"
    }
  }
  ```
</ResponseExample>

***

## Stop Process

Stop a running execution process.

```http theme={null}
POST /api/execution-processes/:id/stop
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "proc_abc123",
    "status": "stopped",
    "stoppedAt": "2024-01-15T10:35:00Z",
    "duration": 300000
  }
}
```

***

## WebSocket: Stream Process Logs

Stream real-time process logs via WebSocket.

### Raw Logs Stream

```
ws://localhost:8887/ws/execution-processes/:id/logs/raw
```

Streams raw, unprocessed log output from the execution process.

**Example**:

```javascript theme={null}
const ws = new WebSocket('ws://localhost:8887/ws/execution-processes/proc_abc123/logs/raw');

ws.onmessage = (event) => {
  console.log('Raw log:', event.data);
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};
```

### Normalized Logs Stream

```
ws://localhost:8887/ws/execution-processes/:id/logs/normalized
```

Streams processed, structured log messages.

**Example**:

```javascript theme={null}
const ws = new WebSocket('ws://localhost:8887/ws/execution-processes/proc_abc123/logs/normalized');

ws.onmessage = (event) => {
  const log = JSON.parse(event.data);
  // { level: 'info', message: '...', timestamp: '...', source: 'executor' }
  console.log(`[${log.level}] ${log.message}`);
};
```

**Message Format**:

```json theme={null}
{
  "level": "info",
  "message": "Generating authentication logic",
  "timestamp": "2024-01-15T10:30:45Z",
  "source": "executor",
  "metadata": {
    "file": "src/auth.ts",
    "action": "code_generation"
  }
}
```

***

## WebSocket: Stream All Processes

Monitor all execution processes in real-time.

```
ws://localhost:8887/ws/execution-processes
```

Receives updates when any process status changes.

**Example**:

```javascript theme={null}
const ws = new WebSocket('ws://localhost:8887/ws/execution-processes');

ws.onmessage = (event) => {
  const update = JSON.parse(event.data);
  // { type: 'process_started', processId: '...', ... }
  // { type: 'process_completed', processId: '...', ... }
  // { type: 'process_failed', processId: '...', error: '...' }
  console.log('Process update:', update);
};
```

**Event Types**:

* `process_started` - New process began execution
* `process_progress` - Progress update
* `process_completed` - Process finished successfully
* `process_failed` - Process encountered error
* `process_stopped` - Process was stopped by user

***

## SDK Examples

```typescript theme={null}
import { ForgeClient } from '@automagik/forge-sdk';

const forge = new ForgeClient();

// List running processes
const processes = await forge.processes.list({
  status: 'running'
});

// Get process details
const process = await forge.processes.get('proc_abc123');

// Stop a process
await forge.processes.stop('proc_abc123');

// Monitor progress
const interval = setInterval(async () => {
  const proc = await forge.processes.get('proc_abc123');
  console.log(`Progress: ${proc.progress.percentage}%`);

  if (proc.status !== 'running') {
    clearInterval(interval);
  }
}, 1000);

// Stream raw logs via WebSocket
const rawWs = new WebSocket('ws://localhost:8887/ws/execution-processes/proc_abc123/logs/raw');
rawWs.onmessage = (event) => console.log('Raw:', event.data);

// Stream normalized logs via WebSocket
const normalizedWs = new WebSocket('ws://localhost:8887/ws/execution-processes/proc_abc123/logs/normalized');
normalizedWs.onmessage = (event) => {
  const log = JSON.parse(event.data);
  console.log(`[${log.level}] ${log.message}`);
};

// Monitor all processes
const allProcessesWs = new WebSocket('ws://localhost:8887/ws/execution-processes');
allProcessesWs.onmessage = (event) => {
  const update = JSON.parse(event.data);
  console.log(`Process ${update.type}:`, update.processId);
};
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Attempts API" icon="flask" href="/forge/api/attempts">
    Manage task attempts
  </Card>

  <Card title="Tasks API" icon="list-check" href="/forge/api/tasks">
    Create and manage tasks
  </Card>
</CardGroup>