Fetch a cron schedule
const url = 'https://example.com/v1/schedules/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://example.com/v1/schedules/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \ --header 'Authorization: Bearer <token>'Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”TriggerId — the trigger id (a UUID).
Query Parameters
Section titled “Query Parameters”Include the next N occurrences (upcoming), 1 to 20.
Responses
Section titled “Responses”Schedule record.
A schedule: what it runs (a flow at a version, or an agent), when (a cron expression in a timezone), as whom (its owner), and what it does after a gap or while a run is still going.
object
Domain-friendly alias for triggerId — the trigger id (a UUID). Use interchangeably in admin URLs.
A schedule that runs a flow: the flow, at flowVersion.
A schedule that runs an agent: the agent, at agentVersion, else its version pinned for the schedule’s project (else the latest), as a run that names none.
A schedule that starts Improve runs: on this agent, in this project (the schedule’s), when the project has enough new corrections sorted to improve since its last Improve run (input: how many, whose, and what a run and the month may cost). An agent and project have one at most.
object
The schedule’s own project. Absent from older servers, and on a schedule registered for a tenant or an org before Improve schedules worked in a project: its fires are refused until its target is saved with the schedule’s project.
The schedule’s project: its runs are this project’s.
Who its runs act as. A person: a personal trigger, which only they or a project admin change. A service account: a shared trigger. Only a take-over (POST …/owner) changes it. Checked again at every fire.
object
The owner’s name at the time of the response: the person’s display name, or the service account’s name. Absent when it can’t be read (no directory, a removed account) and from a runtime before Kindgi 0.1.6: show the id then.
Set when the owner is the trigger’s project’s own service account (runAsProject): the trigger is shared, and runs as the project. Show it as “This project”. Absent otherwise.
5- or 6-field cron expression (croner-compatible). 6-field enables second precision.
IANA timezone (e.g. UTC, America/New_York). Absent → UTC.
Static input handed to the run on every fire. Absent → {}.
After a gap (the runtime was down, or a fire is later than startingDeadlineSeconds): latest runs once, for the latest missed occurrence, and its fire says how many it missed; skip drops the missed occurrences. Never a run per missed occurrence. A tenant’s suspension isn’t caught up either way: once the tenant is restored, a schedule that’s on fires next at its first occurrence after the restore.
When an occurrence comes while the previous run of this schedule is still running: skip records the fire as skipped; allow starts another run.
How late a fire may start and still count as on time; past it, catchUp applies.
Lifecycle status. Only active triggers fire. Tombstoned rows are excluded from every read path.
Why the runtime paused it: repeated fires that were refused (the owner lost access) or failed. Skipped fires (an overlap, an erasure in progress) never count. For an Improve schedule, owner-lost-publish pauses it at once: its owner no longer has publish on the agent. Saving it with a new owner resumes it.
For an Improve schedule whose month’s Improve runs have reached its monthly cap (input.monthCapUsd): when it starts again by itself, the 1st of next month (UTC). It stays active, and its fires until then are skipped. Absent otherwise.
Why it waits until pausedUntil: its month’s cap.
The trigger’s newest version (GET …/versions): one more for each change to what it runs, when, as whom or with what. Absent until its first version.
The tools whose calls in this schedule’s runs don’t wait for a person’s yes, though a tool asks for one in a run no person started (needsApprovalWhenUnattended). Absent: none. Each tool by its id, with no wildcard or pattern, and only tools this trigger’s flow or agent calls. It lifts only that wait: the tenant’s approval rules, the agent’s own rules, the permission check (as the trigger’s owner) and the tool’s own limits all still apply.
Wall-clock time of the next scheduled fire. null on paused rows if the cron scheduler never re-armed.
The next occurrences, when the request asked for them (?upcoming=N).
Example
{ "owner": { "kind": "user", "isProjectAccount": true }, "catchUp": "latest", "overlap": "skip", "status": "active", "pausedReason": "month-cap"}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}No cron trigger with that id, or the row was tombstoned.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}