One target, one durable job

Use a job when one platform operation applies to one target. Creation returns immediately; workers run the provider call independently and persist progress, retries, settlement and the final result.

cURL

curl -X POST "https://api.caelario.com/v1/jobs" \
  -H "X-API-Key: $CAELARIO_API_KEY" \
  -H "Idempotency-Key: 5960de23-70f4-4d42-a697-29f701ae1431" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "operation": "profile",
    "target": "nike",
    "include_posts": 5
  }'

Response202 Acceptedcontent-type: application/json

JSON

{
  "id": "8587ec50-...-9a7b",
  "platform": "instagram",
  "operation": "profile",
  "target": "nike",
  "requested_limit": 1,
  "include_posts": 5,
  "status": "queued",
  "attempts": 0,
  "max_attempts": 3,
  "progress_stage": "queued",
  "progress_message": "Waiting for a worker",
  "progress_current": 0,
  "progress_total": 6,
  "heartbeat_at": null,
  "next_attempt_at": null,
  "cancel_requested_at": null,
  "result_count": null,
  "billed_units": 0,
  "credit_rate": 1,
  "billed_credits": 0,
  "result": null,
  "error": null,
  "created_at": "2026-08-23T12:00:00Z",
  "started_at": null,
  "finished_at": null,
  "cached": false,
  "deduplicated": false,
  "idempotent_replay": false
}

Lifecycle

queuedCredits reserved→runningAttempts and heartbeat→completedDelivered results billed

Retryable upstream, rate-limit and egress failures move back to queued with a future next_attempt_at. The original credit reservation remains intact.

Completed job response

Once terminal, the same resource contains the normalized result, final count and actual credit settlement. Failed jobs return result: null and a structured error object instead.

Response200 OKcontent-type: application/json

JSON

{
  "id": "8587ec50-...-9a7b",
  "platform": "instagram",
  "operation": "profile",
  "target": "nike",
  "requested_limit": 1,
  "include_posts": 5,
  "status": "completed",
  "attempts": 1,
  "max_attempts": 3,
  "progress_stage": "completed",
  "progress_message": "Extraction completed",
  "progress_current": 6,
  "progress_total": 6,
  "heartbeat_at": "2026-08-23T12:00:04Z",
  "next_attempt_at": null,
  "cancel_requested_at": null,
  "result_count": 6,
  "billed_units": 6,
  "credit_rate": 1,
  "billed_credits": 6,
  "result": {
    "profile": {
      "platform": "instagram",
      "username": "nike",
      "display_name": "Nike",
      "is_verified": true
    },
    "posts": [
      {
        "kind": "post",
        "platform": "instagram",
        "username": "nike",
        "caption": "Example public post"
      }
    ]
  },
  "error": null,
  "created_at": "2026-08-23T12:00:00Z",
  "started_at": "2026-08-23T12:00:01Z",
  "finished_at": "2026-08-23T12:00:04Z",
  "cached": false,
  "deduplicated": false,
  "idempotent_replay": false
}

FieldMeaning

statusqueued, running, completed, failed or cancelled

progress_*Current stage, message, delivered count and expected total

resultNormalized profile, content, comments or transcript payload when completed

errorStructured terminal provider error when the job fails

billed_creditsFinal credits charged for delivered results

cached / deduplicatedWhether Caelario reused ready or already-running work

Idempotent submission

Generate one Idempotency-Key for each intended job. If connection loss makes the first response uncertain, repeat the exact request with the same key. Caelario returns the original job without reserving twice.

Cancel and export

POST /v1/jobs/{job_id}/cancel

Queued work cancels immediately. Running work is cancelled cooperatively and its eventual provider result is discarded.

GET /v1/jobs/{job_id}/export?format=csv

Exports support json, csv, and xlsx after completion.