Processes

curl http://localhost:8887/api/processes?status=running

const response = await fetch('http://localhost:8887/api/processes?status=running');
const data = await response.json();

import requests

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

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

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

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.

GET /api/processes

Query Parameters

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

curl http://localhost:8887/api/processes?status=running

const response = await fetch('http://localhost:8887/api/processes?status=running');
const data = await response.json();

import requests

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

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

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Get Process

Get detailed process information.

GET /api/processes/:id

Example Response

{
  "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.

POST /api/processes/:id/cancel

curl -X POST http://localhost:8887/api/processes/proc_abc123/cancel

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

import requests

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

{
  "success": true,
  "data": {
    "id": "proc_abc123",
    "status": "cancelled",
    "cancelledAt": "2024-01-15T10:32:00Z"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Get Process Logs

Stream real-time logs from a process.

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

curl "http://localhost:8887/api/processes/proc_abc123/logs?follow=true"

Get Process Metrics

Get resource usage metrics.

GET /api/processes/:id/metrics

const response = await fetch('http://localhost:8887/api/processes/proc_abc123/logs?follow=true');
const data = await response.json();

import requests

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

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

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Stop Process

Stop a running execution process.

POST /api/execution-processes/:id/stop

Example Response

{
  "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:

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:

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:

{
  "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:

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

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

Attempts API

Manage task attempts

Tasks API

Create and manage tasks

Attempts Approvals

Getting Started

Learn

Configuration

Reference

Troubleshooting

Overview

List Processes

Query Parameters

Get Process

Example Response

Cancel Process

Get Process Logs

Query Parameters

Stop Process

Example Response

WebSocket: Stream Process Logs

Raw Logs Stream

Normalized Logs Stream

WebSocket: Stream All Processes

SDK Examples

Next Steps

Attempts API

Tasks API

​Overview

​List Processes

​Query Parameters

​Get Process

​Example Response

​Cancel Process

​Get Process Logs

​Query Parameters

​Stop Process

​Example Response

​WebSocket: Stream Process Logs

​Raw Logs Stream

​Normalized Logs Stream

​WebSocket: Stream All Processes

​SDK Examples

​Next Steps

Attempts API

Tasks API

Overview

List Processes

Query Parameters

Get Process

Example Response

Cancel Process

Get Process Logs

Query Parameters

Stop Process

Example Response

WebSocket: Stream Process Logs

Raw Logs Stream

Normalized Logs Stream

WebSocket: Stream All Processes

SDK Examples

Next Steps