Cues

A cue is a declared intent. The first coordination primitive.

What is a cue?

A cue is a declared intent. When, what, where. It is the first of CueAPI's five coordination primitives. You declare a cue once. CueAPI dispatches work every time it fires, retries on failure, and verifies the outcome against your policy.

Every cue has:

Field	Description
`id`	Unique identifier (format: `cue_xxxxxxxxxxxx`)
`name`	Human-readable name you choose
`status`	`active`, `paused`, `completed`, or `failed`
`schedule`	When to fire (cron or one-time)
`callback`	Where to deliver (URL for webhook transport)
`transport`	`webhook` (push) or `worker` (pull)
`payload`	JSON body sent with each execution
`next_run`	Next scheduled fire time
`run_count`	How many times this cue has fired successfully

Recurring vs. one-time

Recurring

Fires on a cron schedule. Stays active after each fire. Calculates the next run time automatically.

json

{
  "schedule": {
    "type": "recurring",
    "cron": "0 9 * * 1-5",
    "timezone": "America/New_York"
  }
}

One-time

Fires once at the specified time. Status changes to completed on success or failed after exhausting retries.

json

{
  "schedule": {
    "type": "once",
    "at": "2026-03-15T14:00:00Z"
  }
}

Cue lifecycle

created (active) → fires → active (recurring) or completed (one-time)
                          → failed (one-time, retries exhausted)

active ↔ paused (via PATCH)

active → deleted (via DELETE)

active: scheduled and will fire at next_run
paused: schedule suspended, next_run cleared, can be resumed
completed: one-time cue fired successfully
failed: one-time cue exhausted all retry attempts

Pause and resume

Pausing a cue stops it from firing. Resuming recalculates the next run time from now.

bash

# Pause
curl -X PATCH https://api.cueapi.ai/v1/cues/{cue_id} \
  -H "Authorization: Bearer cue_sk_..." \
  -d '{"status": "paused"}'
 
# Resume
curl -X PATCH https://api.cueapi.ai/v1/cues/{cue_id} \
  -H "Authorization: Bearer cue_sk_..." \
  -d '{"status": "active"}'

Plan limits

Each plan has a maximum number of active cues:

Plan	Max active cues
Free	10
Pro	100
Scale	500

Creating a cue beyond your limit returns 403 cue_limit_exceeded. Upgrade your plan or delete unused cues.

Previous← Authentication NextExecutions →