Choose immediate or durable execution

POST /v1/extract returns one bounded target directly. POST /v1/jobs returns a durable job ID immediately while workers persist progress, retries, settlement and the final result. The request shape and pricing are the same.

ImmediatePOST /v1/extract

One bounded target, completed response.

DurablePOST /v1/jobs

Longer work with polling and export.

cURL

curl -X POST "https://api.caelario.com/v1/jobs" \
  -H "X-API-Key: $CAELARIO_API_KEY" \
  -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": "Queued. Your extraction will start shortly.",
  "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,
  "results_per_credit": 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,
  "results_per_credit": 1,
  "billed_credits": 11,
  "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

Optional retry protection

Caelario creates request, job and batch IDs internally; ordinary clients do not need to generate them. If your client automatically retries a write after a timeout or lost response, add one Idempotency-Key and reuse it with the exact same body. Caelario then returns the original work instead of 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.