Scheduling

Store a request recipe and recurrence

A schedule does not perform extraction itself. When due, it dispatches the same normal job or batch you would create through the immediate endpoints.

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"
  }'

{
  "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": []
}

Recurrence rules

Use an IANA timezone such as Europe/Amsterdam. starts_at must include a UTC offset. Daylight-saving changes preserve the configured local wall-clock time.

Credits are checked at dispatch

Creating a schedule reserves nothing. Each occurrence checks and reserves credits only when its job or batch is dispatched. An unaffordable batch is recorded as skipped_credits; Caelario does not create a partial batch.

Control a schedule