Skip to main content
Execute code in the background and return immediately. The code continues running asynchronously, and you can check its status using the process ID.

​
Endpoint

POST /execute/background

​
Request

​
Headers

Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

​
Body Parameters

ParameterTypeRequiredDescription
codestringYesCode to execute
languagestringNoLanguage (default: python)
timeoutintegerNoMax execution time in seconds (default: 300)
working_dirstringNoWorking directory
envobjectNoEnvironment variables
namestringNoProcess name for identification

​
Example Request

curl -X POST https://sandbox_abc123xyz.hopx.dev/execute/background \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import time\nfor i in range(10):\n    print(f\"Step {i+1}/10\")\n    time.sleep(1)\nprint(\"Done!\")",
    "language": "python",
    "name": "long-task"
  }'

​
Response

​
Success (200 OK)

{
  "process_id": "proc_abc123",
  "execution_id": "exec_xyz789",
  "status": "running"
}

​
Response Fields

FieldTypeDescription
process_idstringProcess ID (use to check status or kill)
execution_idstringExecution ID
statusstringInitial status (queued or running)

​
Status Codes

CodeDescription
200Process started
400Invalid request
401Unauthorized
500Failed to start process

​
Check Process Status

Use the List Processes endpoint to check status: 
curl https://sandbox_abc123xyz.hopx.dev/execute/processes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Response: 
{
  "processes": [
    {
      "process_id": "proc_abc123",
      "execution_id": "exec_xyz789",
      "name": "long-task",
      "status": "running",
      "language": "python",
      "started_at": "2025-01-28T00:00:00Z",
      "stdout": "Step 1/10\nStep 2/10\n",
      "stderr": "",
      "exit_code": null
    }
  ],
  "count": 1
}

​
Kill Background Process

Use the Kill Process endpoint to terminate: 
curl -X DELETE https://sandbox_abc123xyz.hopx.dev/execute/kill \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "process_id": "proc_abc123"
  }'

​
Use Cases

​
Long-Running Data Processing

curl -X POST https://sandbox_abc123xyz.hopx.dev/execute/background \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import pandas as pd\nimport time\n\nprint(\"Processing large dataset...\")\ntime.sleep(30)\ndf = pd.read_csv(\"/workspace/large_file.csv\")\nresult = df.groupby(\"category\").sum()\nresult.to_csv(\"/workspace/result.csv\")\nprint(\"Processing complete!\")",
    "language": "python",
    "timeout": 600,
    "name": "data-processing"
  }'

​
Model Training

curl -X POST https://sandbox_abc123xyz.hopx.dev/execute/background \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "from sklearn.ensemble import RandomForestClassifier\nimport numpy as np\nimport time\n\nprint(\"Training model...\")\nX = np.random.rand(10000, 20)\ny = np.random.randint(0, 2, 10000)\n\nmodel = RandomForestClassifier(n_estimators=100)\nmodel.fit(X, y)\n\nprint(f\"Model accuracy: {model.score(X, y):.2f}\")\nprint(\"Training complete!\")",
    "language": "python",
    "timeout": 1800,
    "name": "model-training"
  }'

​
Monitoring Background Process

#!/bin/bash
PROCESS_ID="proc_abc123"

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

​
Parallel Execution

#!/bin/bash
# Start multiple background tasks
for i in {1..5}; do
  curl -X POST https://sandbox_abc123xyz.hopx.dev/execute/background \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{
      \"code\": \"import time\\ntime.sleep(10)\\nprint('Task $i complete')\",
      \"language\": \"python\",
      \"name\": \"task-$i\"
    }"
  
  echo "Started task $i"
done

echo "All tasks started, check status:"
curl https://sandbox_abc123xyz.hopx.dev/execute/processes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Next Steps