Skip to main content
POST
http://127.0.0.1:8005
/
api
/
v1
/
runs
/
{job_id}
/
cancel
curl -X POST http://127.0.0.1:8005/api/v1/runs/run_abc123/cancel

{
  "job_id": "run_abc123",
  "status": "cancelled",
  "cancelled_at": "2025-01-01T00:05:00Z"
}
Cancel a running or queued async job. Jobs that have already completed cannot be cancelled.
​
job_id
string
required
The unique job identifier (e.g., run_abc123).

​
Response

​
job_id
string
required
Unique job identifier.
​
status
string
required
Updated job status (cancelled).
​
cancelled_at
string
required
ISO 8601 timestamp of cancellation.
curl -X POST http://127.0.0.1:8005/api/v1/runs/run_abc123/cancel

{
  "job_id": "run_abc123",
  "status": "cancelled",
  "cancelled_at": "2025-01-01T00:05:00Z"
}

​
Cancellation Behavior

  • Queued jobs: Immediately marked as cancelled, never started
  • Running jobs: Sent a cancellation signal; may take a moment to stop
  • Completed jobs: Cannot be cancelled (returns 400 error)

​
Example: Submit with Timeout and Cancel

import httpx
import time
import threading

API_URL = "http://127.0.0.1:8005"

def submit_with_client_timeout(prompt, timeout_seconds=60):
    # Submit job
    response = httpx.post(f"{API_URL}/api/v1/runs", json={"prompt": prompt})
    job_id = response.json()["job_id"]
    print(f"Submitted job: {job_id}")
    
    start_time = time.time()
    
    while True:
        # Check if we've exceeded our client-side timeout
        if time.time() - start_time > timeout_seconds:
            print(f"Client timeout reached, cancelling job...")
            httpx.post(f"{API_URL}/api/v1/runs/{job_id}/cancel")
            raise TimeoutError(f"Job {job_id} cancelled after {timeout_seconds}s")
        
        status = httpx.get(f"{API_URL}/api/v1/runs/{job_id}").json()
        
        if status["status"] == "succeeded":
            return httpx.get(f"{API_URL}/api/v1/runs/{job_id}/result").json()
        elif status["status"] in ("failed", "cancelled"):
            raise Exception(f"Job {status['status']}")
        
        time.sleep(status.get("retry_after", 2))

try:
    result = submit_with_client_timeout("Complex analysis task", timeout_seconds=30)
    print(f"Result: {result['result']}")
except TimeoutError as e:
    print(f"Timeout: {e}")

​
Error Responses

StatusDescription
400Job already completed (succeeded, failed, or cancelled)
404Job not found
500Internal server error

​
See Also