Skip to main content

Cancel Job

DELETE/api/v1/jobs/{job_id}

Overview​

Cancel a job that is currently queued or processing. Once cancelled, the job cannot be resumed and will not consume further resources.

Path Parameters​

job_idstringrequired

The unique identifier of the job to cancel (UUID format)

Example: 550e8400-e29b-41d4-a716-446655440000

Response​

successboolean

Whether the cancellation was successful

job_idstring

The cancelled job's identifier

statusstring

New job status (always cancelled)

messagestring

Confirmation message

Example Request​

curl -X DELETE https://spideriq.ai/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <your_token>"

Example Response​

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "cancelled",
  "message": "Job cancelled successfully"
}

Cancellation Rules​

warning

Cannot cancel completed jobs: Only jobs in queued or processing status can be cancelled.

Job StatusCan Cancel?Result
queued✅ YesJob removed from queue
processing✅ YesWorker stops processing, partial results discarded
completed❌ NoReturns 400 error
failed❌ NoAlready in terminal state
cancelled❌ NoAlready cancelled

Use Cases​

Cancel Individual Job​

import requests

def cancel_job(job_id, auth_token):
    """Cancel a specific job"""
    url = f"https://spideriq.ai/api/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {auth_token}"}

    response = requests.delete(url, headers=headers)

    if response.status_code == 200:
        print(f"Job {job_id} cancelled successfully")
    elif response.status_code == 400:
        print(f"Cannot cancel: {response.json()['detail']}")
    elif response.status_code == 404:
        print("Job not found")

    return response.json()

Cancel Multiple Jobs​

import requests

def cancel_multiple_jobs(job_ids, auth_token):
    """Cancel multiple jobs"""
    results = []

    for job_id in job_ids:
        url = f"https://spideriq.ai/api/v1/jobs/{job_id}"
        headers = {"Authorization": f"Bearer {auth_token}"}

        try:
            response = requests.delete(url, headers=headers)
            results.append({
                "job_id": job_id,
                "success": response.status_code == 200,
                "status": response.json().get("status"),
                "error": response.json().get("detail")
            })
        except Exception as e:
            results.append({
                "job_id": job_id,
                "success": False,
                "error": str(e)
            })

    return results

# Usage
job_ids = [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440001",
    "770e8400-e29b-41d4-a716-446655440002"
]

results = cancel_multiple_jobs(job_ids, "<your_token>")
for result in results:
    print(f"Job {result['job_id']}: {'✓' if result['success'] else '✗'}")

Cancel All Queued Jobs​

import requests

def cancel_all_queued_jobs(auth_token):
    """Cancel all jobs in queued status"""
    # First, get all queued jobs
    list_url = "https://spideriq.ai/api/v1/jobs/list"
    headers = {"Authorization": f"Bearer {auth_token}"}
    params = {"status_filter": "queued", "page_size": 100}

    response = requests.get(list_url, headers=headers, params=params)
    data = response.json()

    queued_jobs = data.get("jobs", [])
    cancelled_count = 0

    # Cancel each queued job
    for job in queued_jobs:
        job_id = job["job_id"]
        delete_url = f"https://spideriq.ai/api/v1/jobs/{job_id}"

        delete_response = requests.delete(delete_url, headers=headers)

        if delete_response.status_code == 200:
            cancelled_count += 1
            print(f"Cancelled job {job_id}")

    print(f"Total cancelled: {cancelled_count} jobs")
    return cancelled_count

Cancellation Timing​

info

Queued jobs: Cancelled immediately and removed from the queue.

info

Processing jobs: Worker receives cancellation signal and stops within 1-3 seconds. Partial results are discarded.

After Cancellation​

Once cancelled:

  • Job status becomes cancelled
  • Job remains in your job list (visible in /jobs/list)
  • Results endpoint returns 410 Gone
  • Job cannot be resumed or restarted (must submit a new job)

Error Handling​

import requests

def safe_cancel_job(job_id, auth_token):
    """Cancel job with comprehensive error handling"""
    url = f"https://spideriq.ai/api/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {auth_token}"}

    try:
        response = requests.delete(url, headers=headers)

        if response.status_code == 200:
            return {"success": True, "message": "Job cancelled"}

        elif response.status_code == 400:
            error = response.json()["detail"]
            return {"success": False, "reason": "cannot_cancel", "error": error}

        elif response.status_code == 404:
            return {"success": False, "reason": "not_found"}

        elif response.status_code == 401:
            return {"success": False, "reason": "unauthorized"}

        else:
            return {"success": False, "reason": "unknown", "status": response.status_code}

    except requests.exceptions.RequestException as e:
        return {"success": False, "reason": "network_error", "error": str(e)}

# Usage
result = safe_cancel_job("550e8400-e29b-41d4-a716-446655440000", "<your_token>")

if result["success"]:
    print("Job cancelled successfully")
else:
    print(f"Failed to cancel: {result['reason']}")

Best Practices​

tip

Check status first: Before cancelling, verify the job is in a cancellable state using the /status endpoint to avoid unnecessary errors.

warning

No refunds: Cancelled jobs may still count toward usage metrics depending on when they were cancelled.

ℹ️

Get Job Status

Check if job is cancellable

📋

List Jobs

Find jobs to cancel

📨

Submit Job

Create a replacement job

📃

Get Results

Returns 410 for cancelled jobs