Skip to main content
A scheduled job fires at a fixed instant or at a fixed interval. Exactly one of every_secs / at_ms is required; cron expressions are deliberately unsupported. The ticker advances next_run_ms before running a job, so a restart or a second replica cannot fire the same instant twice; a one-shot job is disabled after firing.

Endpoints

Authentication

Authorization: Bearer <api_key> or Authorization: ApiKey <key>. Optional if AGENT_CLOUD_API_KEY is unset. Every row is scoped by principal_id.

Request body

string
required
Job name.
integer
Interval in seconds; mutually exclusive with at_ms.
integer
Epoch milliseconds for a one-shot trigger (a past instant still fires on the next tick); mutually exclusive with every_secs.
object
JSON payload handed to the runtime when the job fires (e.g. {"prompt": "..."}).
Supplying neither or both trigger fields returns 400; deleting another tenant’s id returns 403, an unknown id 404.

Response

string
Job id (server-generated when omitted).
string
Always scheduled_job.
string
Job name.
integer
Interval in seconds, or null.
integer
One-shot trigger instant, or null.
object
Trigger payload.
boolean
Whether the job is active; false after a one-shot fires.
integer
Epoch milliseconds of the next fire; null when disabled.