Background jobs

Some requests start work that takes longer than one HTTP request, such as running the case pipeline. They return 202 Accepted with a job_id.

Method	Path	What it does
GET	/jobs/{jobId}	Get a job
POST	/jobs/{jobId}/cancel	Cancel a job
POST	/jobs/{jobId}/retry	Retry a job

Get a job

GET/jobs/{jobId}Read onlyAPI key

cURL

curl https://api.recovai.ai/jobs/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918 \
  -H "X-API-Key: $RECOVAI_API_KEY"

PHP

<?php
$ch = curl_init('https://api.recovai.ai/jobs/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('RECOVAI_API_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$result = json_decode($body, true);
if ($status >= 400) {
    throw new RuntimeException($result['error'] . ': ' . ($result['details'] ?? ''));
}

Node.js

const res = await fetch('https://api.recovai.ai/jobs/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.RECOVAI_API_KEY },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.details ?? ''}`);

Python

import os
import requests

r = requests.get(
    "https://api.recovai.ai/jobs/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
    headers={"X-API-Key": os.environ["RECOVAI_API_KEY"]},
    timeout=60,
)
data = r.json()
if not r.ok:
    raise RuntimeError(f"{data['error']}: {data.get('details', '')}")

Response 200 OK

{
  "job": {
    "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
    "status": "done",
    "progress": { "phase": "processing" },
    "result": {
      "steps": [
        "Competing-lien search completed — no competing UCC filings found",
        "..."
      ],
      "readiness": "strategy_ready",
      "targets": 3
    },
    "error": null,
    "attempt": 1,
    "max_attempts": 3,
    "started_at": "2026-10-14T15:46:00.000Z",
    "updated_at": "2026-10-14T15:46:41.000Z",
    "finished_at": "2026-10-14T15:46:41.000Z",
    "finished": true,
    "cancellable": false,
    "retryable": false
  }
}

status	Meaning
queued	Waiting to start.
running	In progress; progress shows the current phase.
retry_wait	Failed once and will retry automatically.
done	Finished successfully; see result.
failed, dead_letter	Finished with an error; see error.
cancelled	Cancelled.

Poll every few seconds until finished is true. Jobs expire some time after they finish; an expired or unknown job returns 404 job_not_found.

For the case pipeline, result has steps (what each step did, in plain English), the case’s new readiness, and how many targets the case has. progress shows the last reported phase while the job runs.

Cancel a job

POST/jobs/{jobId}/cancelChanges dataAPI key

Cancels a job that has not started (queued or retry_wait): returns 200 OK with the cancelled job. Some running jobs can be asked to stop: then you get 202 Accepted with "cancellation_requested": true, and the job stops at its next safe point. Check cancellable on the job first.

Example

cURL

curl -X POST https://api.recovai.ai/jobs/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/cancel \
  -H "X-API-Key: $RECOVAI_API_KEY"

PHP

<?php
$ch = curl_init('https://api.recovai.ai/jobs/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/cancel');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('RECOVAI_API_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$result = json_decode($body, true);
if ($status >= 400) {
    throw new RuntimeException($result['error'] . ': ' . ($result['details'] ?? ''));
}

Node.js

const res = await fetch('https://api.recovai.ai/jobs/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/cancel', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.RECOVAI_API_KEY },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.details ?? ''}`);

Python

import os
import requests

r = requests.post(
    "https://api.recovai.ai/jobs/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/cancel",
    headers={"X-API-Key": os.environ["RECOVAI_API_KEY"]},
    timeout=60,
)
data = r.json()
if not r.ok:
    raise RuntimeError(f"{data['error']}: {data.get('details', '')}")

Errors: 404 job_not_found, 409 job_not_cancellable.

Retry a job

POST/jobs/{jobId}/retryChanges dataAPI key

Runs a failed, dead_letter or cancelled job again. Returns 202 Accepted with the requeued job. Check retryable on the job first.

Example

cURL

curl -X POST https://api.recovai.ai/jobs/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/retry \
  -H "X-API-Key: $RECOVAI_API_KEY"

PHP

<?php
$ch = curl_init('https://api.recovai.ai/jobs/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/retry');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('RECOVAI_API_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$result = json_decode($body, true);
if ($status >= 400) {
    throw new RuntimeException($result['error'] . ': ' . ($result['details'] ?? ''));
}

Node.js

const res = await fetch('https://api.recovai.ai/jobs/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/retry', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.RECOVAI_API_KEY },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error}: ${data.details ?? ''}`);

Python

import os
import requests

r = requests.post(
    "https://api.recovai.ai/jobs/7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918/retry",
    headers={"X-API-Key": os.environ["RECOVAI_API_KEY"]},
    timeout=60,
)
data = r.json()
if not r.ok:
    raise RuntimeError(f"{data['error']}: {data.get('details', '')}")

Errors: 404 job_not_found, 409 job_not_retryable, 409 job_already_queued (the same work is already queued or running).