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

# List Background Processes

> List all background code execution processes in sandboxes and check their status using the HopX VM Agent API. Monitor running background processes, check execution status, and track process lifecycle. Learn how to use GET /processes endpoint to list processes, view status, and manage background executions. Includes request examples and response formats.

List all background execution processes started with the background execution endpoint. Check their status, output, and execution details.

## Endpoint

```
GET /execute/processes
```

## Request

### Headers

```
Authorization: Bearer YOUR_JWT_TOKEN
```

### Example Request

```bash theme={null}
curl https://sandbox_abc123xyz.hopx.dev/execute/processes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## Response

### Success (200 OK)

```json theme={null}
{
  "processes": [
    {
      "process_id": "proc_abc123",
      "execution_id": "exec_xyz789",
      "name": "data-processing",
      "status": "running",
      "language": "python",
      "started_at": "2025-01-28T00:00:00Z",
      "completed_at": null,
      "stdout": "Processing step 1/10\nProcessing step 2/10\n",
      "stderr": "",
      "exit_code": null,
      "execution_time": 15.5
    },
    {
      "process_id": "proc_def456",
      "execution_id": "exec_uvw012",
      "name": "model-training",
      "status": "completed",
      "language": "python",
      "started_at": "2025-01-27T23:00:00Z",
      "completed_at": "2025-01-27T23:30:00Z",
      "stdout": "Training complete! Accuracy: 0.95\n",
      "stderr": "",
      "exit_code": 0,
      "execution_time": 1800.3
    }
  ],
  "count": 2
}
```

### Response Fields

| Field       | Type    | Description               |
| ----------- | ------- | ------------------------- |
| `processes` | array   | Array of process objects  |
| `count`     | integer | Total number of processes |

### Process Object

| Field            | Type    | Description                                        |
| ---------------- | ------- | -------------------------------------------------- |
| `process_id`     | string  | Process ID                                         |
| `execution_id`   | string  | Execution ID                                       |
| `name`           | string  | Process name (if provided)                         |
| `status`         | string  | Status: `queued`, `running`, `completed`, `failed` |
| `language`       | string  | Programming language                               |
| `started_at`     | string  | ISO 8601 start timestamp                           |
| `completed_at`   | string  | ISO 8601 completion timestamp (if complete)        |
| `stdout`         | string  | Standard output                                    |
| `stderr`         | string  | Standard error                                     |
| `exit_code`      | integer | Exit code (null if still running)                  |
| `execution_time` | number  | Execution time in seconds                          |

## Status Codes

| Code | Description  |
| ---- | ------------ |
| 200  | Success      |
| 401  | Unauthorized |

## Process Statuses

| Status      | Description                     |
| ----------- | ------------------------------- |
| `queued`    | Process is queued for execution |
| `running`   | Process is currently running    |
| `completed` | Process completed successfully  |
| `failed`    | Process failed with error       |

## Use Cases

### Monitor All Processes

```bash theme={null}
curl https://sandbox_abc123xyz.hopx.dev/execute/processes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | jq '.'
```

### Check Specific Process

```bash theme={null}
curl https://sandbox_abc123xyz.hopx.dev/execute/processes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | \
  jq '.processes[] | select(.process_id == "proc_abc123")'
```

### Filter Running Processes

```bash theme={null}
curl https://sandbox_abc123xyz.hopx.dev/execute/processes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | \
  jq '.processes[] | select(.status == "running")'
```

### Get Process Output

```bash theme={null}
curl https://sandbox_abc123xyz.hopx.dev/execute/processes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | \
  jq -r '.processes[] | select(.process_id == "proc_abc123") | .stdout'
```

### Wait for Completion

```bash theme={null}
#!/bin/bash
PROCESS_ID="proc_abc123"

while true; do
  RESPONSE=$(curl -s https://sandbox_abc123xyz.hopx.dev/execute/processes \
    -H "Authorization: Bearer YOUR_JWT_TOKEN")
  
  PROCESS=$(echo "$RESPONSE" | jq ".processes[] | select(.process_id == \"$PROCESS_ID\")")
  STATUS=$(echo "$PROCESS" | jq -r '.status')
  
  echo "Status: $STATUS"
  
  if [ "$STATUS" == "completed" ]; then
    echo "Output:"
    echo "$PROCESS" | jq -r '.stdout'
    break
  elif [ "$STATUS" == "failed" ]; then
    echo "Error:"
    echo "$PROCESS" | jq -r '.stderr'
    break
  fi
  
  sleep 5
done
```

### List Completed Processes

```bash theme={null}
curl https://sandbox_abc123xyz.hopx.dev/execute/processes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | \
  jq '.processes[] | select(.status == "completed") | {name, execution_time, exit_code}'
```

### Count Processes by Status

```bash theme={null}
curl https://sandbox_abc123xyz.hopx.dev/execute/processes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | \
  jq '[.processes | group_by(.status) | .[] | {status: .[0].status, count: length}]'
```

## Related

* **SDK**: [sandbox.list\_processes()](/sdk/python/sandbox#list_processes) - Python SDK method
* [CLI System Commands](/cli/commands/system) - System operations from CLI

## Next Steps

* **[Background Execution](/api/vm-agent/execute-background)** - Start background processes
* **[Kill Process](/api/vm-agent/kill-process)** - Terminate a running process
* **[Async Execution](/api/vm-agent/execute-async)** - Execute with webhook callbacks