Cancel Run API

Cancel a running async job

Cancel a running or queued async job. Jobs that have already completed cannot be cancelled.

job_id string

The unique job identifier (e.g., run_abc123).

Response

ResponseField string

Unique job identifier.

ResponseField string

Updated job status (cancelled).

ResponseField string

ISO 8601 timestamp of cancellation.

cURL

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

Python

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

CLI

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

400 Bad Request (Already Completed)

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

404 Not Found

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

python

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

Cancel Run API

Response

Cancellation Behavior

Example: Submit with Timeout and Cancel

Error Responses

See Also