Cues

A cue is a scheduled task. Recurring or one-time, webhook or worker.

What is a cue?

A cue is a registered schedule that tells CueAPI when to fire and where to deliver the payload. Think of it as an API-managed cron job with delivery guarantees, retry logic, and execution history.

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 →