Public HTTP surface

All endpoints use JSON unless returning an export. Send X-API-Key on every call. Write endpoints that create work should include an Idempotency-Key.

Download filtered OpenAPI JSON ↗

Discovery and account

Inspect the live capabilities and current workspace before submitting work.

GET/v1/platformsList platform capabilities⌄

Returns every enabled platform operation, limit, credit rate and session requirement.

Response · 200 OK

Response200 OKcontent-type: application/json

JSON

[
  {
    "platform": "instagram",
    "label": "Instagram",
    "operations": [
      {
        "operation": "profile",
        "max_results": 1,
        "credits_per_result": 1,
        "base_credits": 0,
        "requires_session": false
      },
      {
        "operation": "posts",
        "max_results": 50,
        "credits_per_result": 1,
        "base_credits": 0,
        "requires_session": false
      }
    ]
  }
]

GET/v1/accountGet the workspace account⌄

Returns workspace identity, plan limits, role and API concurrency limits.

Response · 200 OK

Response200 OKcontent-type: application/json

JSON

{
  "organization_id": "workspace_01H...",
  "organization_name": "Acme data team",
  "monthly_quota": 10000,
  "rate_limit_per_minute": 60,
  "max_result_limit": 200,
  "max_active_jobs": 10,
  "authenticated_key_id": "key_01H...",
  "auth_type": "api_key",
  "role": "owner",
  "user": null,
  "workspaces": []
}

GET/v1/usage/currentGet current credit usage⌄

Returns available, purchased, promotional, reserved and lifetime credit totals.

Response · 200 OK

Response200 OKcontent-type: application/json

JSON

{
  "period_start": "2026-08-01",
  "credit_limit": 10175,
  "units_used": 82,
  "units_reserved": 0,
  "units_remaining": 10093,
  "credits_used": 82,
  "credits_reserved": 0,
  "credits_remaining": 10093,
  "purchased_credits": 10000,
  "promotional_credits": 175,
  "promotional_expires_at": null,
  "lifetime_purchased": 10000,
  "lifetime_spent": 82
}

Jobs

A job is one operation against one public target.

POST/v1/jobsCreate a job⌄

Validates the request, reserves its maximum credit cost and returns immediately.

Response · 202 Accepted

Example request

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
}

GET/v1/jobsList jobs⌄

Returns the latest workspace jobs. Use the limit query parameter from 1 to 100.

Response · 200 OK

Response200 OKcontent-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
  }]

GET/v1/jobs/{job_id}Get a job⌄

Returns progress, attempts, settlement, result or terminal error.

Response · 200 OK

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
}

POST/v1/jobs/{job_id}/cancelCancel a job⌄

Cancels queued work immediately or requests cooperative cancellation for running work.

Response · 200 OK

Response200 OKcontent-type: application/json

JSON

{
  "id": "8587ec50-...-9a7b",
  "platform": "instagram",
  "operation": "profile",
  "target": "nike",
  "requested_limit": 1,
  "include_posts": 5,
  "status": "cancelled",
  "attempts": 0,
  "max_attempts": 3,
  "progress_stage": "cancelled",
  "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
}

GET/v1/jobs/{job_id}/exportExport a job⌄

Downloads a completed result using format=json, csv or xlsx.

Batches

A batch applies the same operation and limit to an ordered set of targets.

POST/v1/batchesCreate a batch⌄

Creates up to 100 independently retried child jobs in one request.

Response · 202 Accepted

Example request

curl -X POST "https://api.caelario.com/v1/batches" \
  -H "X-API-Key: $CAELARIO_API_KEY" \
  -H "Idempotency-Key: campaign-2026-08-23" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "operation": "posts",
    "targets": ["nike", "adidas", "puma"],
    "limit": 12
  }'

Response202 Acceptedcontent-type: application/json

JSON

{
  "id": "53337f72-...-dc2e",
  "platform": "instagram",
  "operation": "posts",
  "requested_limit": 12,
  "include_posts": 0,
  "target_count": 3,
  "status": "queued",
  "queued_count": 3,
  "running_count": 0,
  "completed_count": 0,
  "failed_count": 0,
  "cancelled_count": 0,
  "result_count": 0,
  "reserved_credits": 36,
  "billed_credits": 0,
  "cancel_requested_at": null,
  "created_at": "2026-08-23T12:05:00Z",
  "jobs": [
    { "id": "job_nike", "target": "nike", "status": "queued" },
    { "id": "job_adidas", "target": "adidas", "status": "queued" },
    { "id": "job_puma", "target": "puma", "status": "queued" }
  ],
  "idempotent_replay": false
}

GET/v1/batchesList batches⌄

Returns recent batches. Set include_jobs=true to include child job summaries.

Response · 200 OK

Response200 OKcontent-type: application/json

JSON

[{
    "id": "53337f72-...-dc2e",
    "platform": "instagram",
    "operation": "posts",
    "requested_limit": 12,
    "include_posts": 0,
    "target_count": 3,
    "status": "queued",
    "queued_count": 3,
    "running_count": 0,
    "completed_count": 0,
    "failed_count": 0,
    "cancelled_count": 0,
    "result_count": 0,
    "reserved_credits": 36,
    "billed_credits": 0,
    "cancel_requested_at": null,
    "created_at": "2026-08-23T12:05:00Z",
    "jobs": [
      { "id": "job_nike", "target": "nike", "status": "queued" },
      { "id": "job_adidas", "target": "adidas", "status": "queued" },
      { "id": "job_puma", "target": "puma", "status": "queued" }
    ],
    "idempotent_replay": false
  }]

GET/v1/batches/{batch_id}Get a batch⌄

Returns aggregate status, result counts, credit settlement and child jobs.

Response · 200 OK

Response200 OKcontent-type: application/json

JSON

{
  "id": "53337f72-...-dc2e",
  "platform": "instagram",
  "operation": "posts",
  "requested_limit": 12,
  "include_posts": 0,
  "target_count": 3,
  "status": "queued",
  "queued_count": 3,
  "running_count": 0,
  "completed_count": 0,
  "failed_count": 0,
  "cancelled_count": 0,
  "result_count": 0,
  "reserved_credits": 36,
  "billed_credits": 0,
  "cancel_requested_at": null,
  "created_at": "2026-08-23T12:05:00Z",
  "jobs": [
    { "id": "job_nike", "target": "nike", "status": "queued" },
    { "id": "job_adidas", "target": "adidas", "status": "queued" },
    { "id": "job_puma", "target": "puma", "status": "queued" }
  ],
  "idempotent_replay": false
}

POST/v1/batches/{batch_id}/cancelCancel a batch⌄

Cancels every child job still owned by and running for the batch.

Response · 200 OK

Response200 OKcontent-type: application/json

JSON

{
  "id": "53337f72-...-dc2e",
  "platform": "instagram",
  "operation": "posts",
  "requested_limit": 12,
  "include_posts": 0,
  "target_count": 3,
  "status": "cancelled",
  "queued_count": 3,
  "running_count": 0,
  "completed_count": 0,
  "failed_count": 0,
  "cancelled_count": 0,
  "result_count": 0,
  "reserved_credits": 36,
  "billed_credits": 0,
  "cancel_requested_at": null,
  "created_at": "2026-08-23T12:05:00Z",
  "jobs": [
    { "id": "job_nike", "target": "nike", "status": "queued" },
    { "id": "job_adidas", "target": "adidas", "status": "queued" },
    { "id": "job_puma", "target": "puma", "status": "queued" }
  ],
  "idempotent_replay": false
}

GET/v1/batches/{batch_id}/exportExport a batch⌄

Downloads all ready child results using format=json, csv or xlsx.

Schedules

Schedules store a reusable request and dispatch normal jobs or batches when due.

POST/v1/schedulesCreate a schedule⌄

Creates a once, daily, weekly or monthly schedule.

Response · 201 Created

Example request

curl -X POST "https://api.caelario.com/v1/schedules" \
  -H "X-API-Key: $CAELARIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily brand monitoring",
    "platform": "x",
    "operation": "posts",
    "targets": ["XDevelopers", "OpenAI"],
    "limit": 20,
    "frequency": "daily",
    "timezone": "Europe/Amsterdam",
    "starts_at": "2026-08-24T09:00:00+02:00",
    "overlap_policy": "skip"
  }'

Response201 Createdcontent-type: application/json

JSON

{
  "id": "schedule_7d3b...91fa",
  "name": "Daily brand monitoring",
  "platform": "x",
  "operation": "posts",
  "targets": ["XDevelopers", "OpenAI"],
  "requested_limit": 20,
  "include_posts": 0,
  "frequency": "daily",
  "timezone": "Europe/Amsterdam",
  "starts_at": "2026-08-24T09:00:00+02:00",
  "next_run_at": "2026-08-24T07:00:00Z",
  "last_run_at": null,
  "status": "active",
  "overlap_policy": "skip",
  "created_at": "2026-08-23T12:10:00Z",
  "updated_at": "2026-08-23T12:10:00Z",
  "runs": []
}

GET/v1/schedulesList schedules⌄

Returns active and paused schedules plus their recent runs.

Response · 200 OK

Response200 OKcontent-type: application/json

JSON

[{
    "id": "schedule_7d3b...91fa",
    "name": "Daily brand monitoring",
    "platform": "x",
    "operation": "posts",
    "targets": ["XDevelopers", "OpenAI"],
    "requested_limit": 20,
    "include_posts": 0,
    "frequency": "daily",
    "timezone": "Europe/Amsterdam",
    "starts_at": "2026-08-24T09:00:00+02:00",
    "next_run_at": "2026-08-24T07:00:00Z",
    "last_run_at": null,
    "status": "active",
    "overlap_policy": "skip",
    "created_at": "2026-08-23T12:10:00Z",
    "updated_at": "2026-08-23T12:10:00Z",
    "runs": []
  }]

GET/v1/schedules/{schedule_id}Get a schedule⌄

Returns recurrence, next run and dispatch history.

Response · 200 OK

Response200 OKcontent-type: application/json

JSON

{
  "id": "schedule_7d3b...91fa",
  "name": "Daily brand monitoring",
  "platform": "x",
  "operation": "posts",
  "targets": ["XDevelopers", "OpenAI"],
  "requested_limit": 20,
  "include_posts": 0,
  "frequency": "daily",
  "timezone": "Europe/Amsterdam",
  "starts_at": "2026-08-24T09:00:00+02:00",
  "next_run_at": "2026-08-24T07:00:00Z",
  "last_run_at": null,
  "status": "active",
  "overlap_policy": "skip",
  "created_at": "2026-08-23T12:10:00Z",
  "updated_at": "2026-08-23T12:10:00Z",
  "runs": []
}

PUT/v1/schedules/{schedule_id}Update a schedule⌄

Replaces the request recipe and recurrence while preserving paused state.

Response · 200 OK

Response200 OKcontent-type: application/json

JSON

{
  "id": "schedule_7d3b...91fa",
  "name": "Daily brand monitoring",
  "platform": "x",
  "operation": "posts",
  "targets": ["XDevelopers", "OpenAI"],
  "requested_limit": 20,
  "include_posts": 0,
  "frequency": "daily",
  "timezone": "Europe/Amsterdam",
  "starts_at": "2026-08-24T09:00:00+02:00",
  "next_run_at": "2026-08-24T07:00:00Z",
  "last_run_at": null,
  "status": "active",
  "overlap_policy": "skip",
  "created_at": "2026-08-23T12:10:00Z",
  "updated_at": "2026-08-23T12:10:00Z",
  "runs": []
}

POST/v1/schedules/{schedule_id}/pausePause a schedule⌄

Stops future automatic dispatches without deleting history.

Response · 200 OK

Response200 OKcontent-type: application/json

JSON

{
  "id": "schedule_7d3b...91fa",
  "name": "Daily brand monitoring",
  "platform": "x",
  "operation": "posts",
  "targets": ["XDevelopers", "OpenAI"],
  "requested_limit": 20,
  "include_posts": 0,
  "frequency": "daily",
  "timezone": "Europe/Amsterdam",
  "starts_at": "2026-08-24T09:00:00+02:00",
  "next_run_at": "2026-08-24T07:00:00Z",
  "last_run_at": null,
  "status": "paused",
  "overlap_policy": "skip",
  "created_at": "2026-08-23T12:10:00Z",
  "updated_at": "2026-08-23T12:10:00Z",
  "runs": []
}

POST/v1/schedules/{schedule_id}/resumeResume a schedule⌄

Reactivates a paused recurring schedule and advances its next run if needed.

Response · 200 OK

Response200 OKcontent-type: application/json

JSON

{
  "id": "schedule_7d3b...91fa",
  "name": "Daily brand monitoring",
  "platform": "x",
  "operation": "posts",
  "targets": ["XDevelopers", "OpenAI"],
  "requested_limit": 20,
  "include_posts": 0,
  "frequency": "daily",
  "timezone": "Europe/Amsterdam",
  "starts_at": "2026-08-24T09:00:00+02:00",
  "next_run_at": "2026-08-24T07:00:00Z",
  "last_run_at": null,
  "status": "active",
  "overlap_policy": "skip",
  "created_at": "2026-08-23T12:10:00Z",
  "updated_at": "2026-08-23T12:10:00Z",
  "runs": []
}

POST/v1/schedules/{schedule_id}/runRun a schedule now⌄

Creates an immediate manual occurrence using the saved recipe.

Response · 202 Accepted

Response202 Acceptedcontent-type: application/json

JSON

{
  "id": "schedule_7d3b...91fa",
  "name": "Daily brand monitoring",
  "platform": "x",
  "operation": "posts",
  "targets": ["XDevelopers", "OpenAI"],
  "requested_limit": 20,
  "include_posts": 0,
  "frequency": "daily",
  "timezone": "Europe/Amsterdam",
  "starts_at": "2026-08-24T09:00:00+02:00",
  "next_run_at": "2026-08-24T07:00:00Z",
  "last_run_at": null,
  "status": "active",
  "overlap_policy": "skip",
  "created_at": "2026-08-23T12:10:00Z",
  "updated_at": "2026-08-23T12:10:00Z",
  "runs": [{ "id": "run_01H...", "trigger": "manual", "status": "queued", "job_id": null, "batch_id": "batch_01H..." }]
}

DELETE/v1/schedules/{schedule_id}Delete a schedule⌄

Soft-deletes the schedule while retaining prior jobs and accounting.

Response · 204 No Content