Skip to main content

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 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

curl https://sandbox_abc123xyz.hopx.dev/execute/processes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Response

​
Success (200 OK)

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

FieldTypeDescription
processesarrayArray of process objects
countintegerTotal number of processes

​
Process Object

FieldTypeDescription
process_idstringProcess ID
execution_idstringExecution ID
namestringProcess name (if provided)
statusstringStatus: queued, running, completed, failed
languagestringProgramming language
started_atstringISO 8601 start timestamp
completed_atstringISO 8601 completion timestamp (if complete)
stdoutstringStandard output
stderrstringStandard error
exit_codeintegerExit code (null if still running)
execution_timenumberExecution time in seconds

​
Status Codes

CodeDescription
200Success
401Unauthorized

​
Process Statuses

StatusDescription
queuedProcess is queued for execution
runningProcess is currently running
completedProcess completed successfully
failedProcess failed with error

​
Use Cases

​
Monitor All Processes

curl https://sandbox_abc123xyz.hopx.dev/execute/processes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | jq '.'

​
Check Specific Process

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

​
Filter Running Processes

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

​
Get Process Output

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

#!/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

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

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

​
Next Steps