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. Run one bounded extraction

Use POST /v1/extract when one target fits the synchronous limit. It returns a completed result directly with final billing, so there is no job to poll.

cURL

curl -X POST "https://api.caelario.com/v1/extract" \
  -H "X-API-Key: $CAELARIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "operation": "profile",
    "target": "nike"
  }'

Response200 OKcontent-type: application/json

JSON

{
  "id": "91eb7b54-...-5d11",
  "platform": "instagram",
  "operation": "profile",
  "target": "nike",
  "requested_limit": 1,
  "include_posts": 0,
  "status": "completed",
  "result_count": 1,
  "billed_units": 1,
  "credit_rate": 1,
  "results_per_credit": 1,
  "billed_credits": 1,
  "result": {
    "platform": "instagram",
    "username": "nike",
    "display_name": "Nike",
    "is_verified": true
  },
  "error": null,
  "cached": false,
  "deduplicated": false,
  "idempotent_replay": false
}

4. Use a durable job for larger work

Use POST /v1/jobs when work may take longer, must survive a closed connection, or needs progress, retries, cancellation and export. Creation returns 202 Accepted immediately.

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
}

Poll with 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.

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.