Cancel Run API

Cancel a running async job

POST /api/v1/runs/{job_id}/cancel

cURL

curl -X POST http://127.0.0.1:8005/api/v1/runs/run_abc123/cancel

import httpx

job_id = "run_abc123"

response = httpx.post(f"http://127.0.0.1:8005/api/v1/runs/{job_id}/cancel")

if response.status_code == 200:
    result = response.json()
    print(f"Job {result['job_id']} cancelled")
elif response.status_code == 400:
    print("Job already completed, cannot cancel")
elif response.status_code == 404:
    print("Job not found")

praisonai run cancel run_abc123

# JSON output
praisonai run cancel run_abc123 --json

200 OK

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

{
  "detail": "Cannot cancel job with status: succeeded"
}

{
  "detail": "Job not found: run_abc123"
}

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

curl -X POST http://127.0.0.1:8005/api/v1/runs/run_abc123/cancel

import httpx

job_id = "run_abc123"

response = httpx.post(f"http://127.0.0.1:8005/api/v1/runs/{job_id}/cancel")

if response.status_code == 200:
    result = response.json()
    print(f"Job {result['job_id']} cancelled")
elif response.status_code == 400:
    print("Job already completed, cannot cancel")
elif response.status_code == 404:
    print("Job not found")

praisonai run cancel run_abc123

# JSON output
praisonai run cancel run_abc123 --json

200 OK

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

{
  "detail": "Cannot cancel job with status: succeeded"
}

{
  "detail": "Job not found: run_abc123"
}

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

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

See Also

• Get Run Status
• Submit Run
• Async Jobs Overview