Skip to content

Jobs API

Inspect background jobs and request a rerun where supported. The current API schema accepts a numeric job ID or a compact derived ID such as JOB-3F-A1B2; do not substitute a UUID or invent a job ID from its name.

Get Job Status

Endpoint: GET /jobs/{id}

curl --fail-with-body --max-time 30 \
  "https://PLATFORM-URL-PLACEHOLDER/v1/api/jobs/JOB_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Replace JOB_ID with the identifier returned for your job. The optional x-user-identifier header follows the workspace-key identity rules.

Response

The job's fields are nested under data.attributes. Example shape with synthetic values:

{
  "data": {
    "id": 123,
    "attributes": {
      "id": 123,
      "task_id": "example-task",
      "status": "pending",
      "type": "example-job-type",
      "request": {},
      "response": {},
      "createdAt": "2026-09-17T09:00:00Z",
      "updatedAt": "2026-09-17T09:00:00Z"
    }
  },
  "meta": {}
}

The schema exposes request and response objects whose contents depend on the job type. Do not assume every job has a progress percentage or a result field.

Job Statuses

The current schema enumerates:

  • pending, in_progress, llm_action_pending
  • user_action_pending, user_action_in_progress, user_action_required
  • completed, failed, failure, stopped

Treat completed as completion and inspect the job response. Surface failure, stopped and user-action states instead of silently polling forever. These job statuses are different from the async Chat API statuses.

Rerun Job

Endpoint: POST /jobs/{id}/rerun

The schema describes rerunning completed, failed or stopped jobs with their existing configuration. A rerun performs work again; check the original failure and possible side effects before requesting one.

curl --fail-with-body --max-time 30 -X POST \
  "https://PLATFORM-URL-PLACEHOLDER/v1/api/jobs/JOB_ID/rerun" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response has top-level success, message, originalJobId, resolvedJobId, newJobId and newJob fields. Use the returned identifier to inspect the new job; do not expect the GET response envelope from this operation.

The description mentions optional request changes, but the inspected operation does not expose a request-body schema. Consult the current interactive documentation before supplying overrides.

Job Types

The schema declares type as a string. Use the returned value and job-specific response rather than assuming a fixed list of types applies to every deployment.

Polling for Job Completion

This example checks the response shape, HTTP status and known job states. Set API_KEY in your process environment and pass an actual job ID. It returns user-action states to the caller for review rather than treating them as success.

import os
import time
import requests

BASE_URL = "https://PLATFORM-URL-PLACEHOLDER/v1/api"

def poll_job(job_id, interval=5, timeout=300):
    if interval <= 0 or timeout <= 0:
        raise ValueError("interval and timeout must be positive")
    deadline = time.monotonic() + timeout
    waiting = {"pending", "in_progress", "llm_action_pending"}
    attention = {"user_action_pending", "user_action_in_progress",
                 "user_action_required"}
    while True:
        remaining = deadline - time.monotonic()
        if remaining <= 0:
            raise TimeoutError("Job polling timed out")
        response = requests.get(
            f"{BASE_URL}/jobs/{job_id}",
            headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
            timeout=(min(5, remaining), min(15, remaining)),
        )
        response.raise_for_status()
        payload = response.json()
        data = payload.get("data") if isinstance(payload, dict) else None
        job = data.get("attributes") if isinstance(data, dict) else None
        if not isinstance(job, dict):
            raise ValueError("Expected job fields under data.attributes")
        status = job.get("status")
        if status == "completed" or status in attention:
            return job
        if status in {"failed", "failure", "stopped"}:
            raise RuntimeError(f"Job ended with status: {status}")
        if status not in waiting:
            raise ValueError(f"Unexpected job status: {status}")
        remaining = deadline - time.monotonic()
        if remaining <= 0:
            raise TimeoutError("Job polling timed out")
        time.sleep(min(interval, remaining))

The polling budget limits repeat requests. Requests' connect/read timeouts bound connection and read inactivity; they are not a hard total download deadline. Handle network errors at the caller and do not automatically rerun a job after a polling failure.

Best Practices

  • Check authorization and HTTP errors before parsing a success body.
  • Use a polling interval and a finite budget; stop on failures or required user action.
  • Treat request/response payloads as potentially sensitive when preparing support evidence.
  • Check the interactive schema for the current contract before integrating.