1. Create a workspace API key

Open Developers in the Caelario dashboard, name the key for the environment that will use it, and copy the secret immediately. The full secret is shown once.

2. Set the environment variable

Shell

export CAELARIO_API_KEY="sda_..."

Production applications should read the key through their secret manager. Keep separate keys for local development, staging and production so each can be revoked independently.

3. Submit one job

The API validates the request, reserves its maximum credit cost and returns 202 Accepted. Extraction continues in the background.

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
}

4. Poll until terminal

Python

import os, time, requests

api = "https://api.caelario.com"
headers = {"X-API-Key": os.environ["CAELARIO_API_KEY"]}

while True:
    job = requests.get(f"{api}/v1/jobs/{job_id}", headers=headers).json()
    if job["status"] in {"completed", "failed", "cancelled"}:
        break
    time.sleep(2)

print(job["result"] if job["status"] == "completed" else job["error"])

Terminal states are completed, failed, and cancelled. A completed response includes the normalized result and final credit settlement.

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
}

5. Export when ready

cURL

curl -o result.xlsx \
  -H "X-API-Key: $CAELARIO_API_KEY" \
  "https://api.caelario.com/v1/jobs/$JOB_ID/export?format=xlsx"

Stored results can be downloaded again without running another extraction or spending more credits.