Skip to content
Kindgi

List cron schedules

View as Markdown
GET
/v1/schedules
curl --request GET \
  --url 'https://example.com/v1/schedules?limit=25&status=active' \
  --header 'Authorization: Bearer <token>'

Cursor-paginated. Tombstoned rows excluded. Optional ?status=active|paused and ?projectId= (one project’s schedules) filters. Each schedule’s owner.displayName is the owner’s name now (the person’s or the service account’s), when it can be read.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 25 >= 1 <= 100

1..100. Default 25.

cursor
string

Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. Absent → first page.

status

Lifecycle status. Only active triggers fire. Tombstoned rows are excluded from every read path.

string
Allowed values: active paused

Filter to triggers at a specific status. Values: active | paused.

projectId
string format: uuid

Only this project’s schedules. A runtime before Kindgi 0.1.6 ignores it and lists every project’s.

Responses

Section titled “Responses”

200

Section titled “200”

Page of schedules.

Media typeapplication/json
object
data
required
Array<object>

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
scheduleId
required

Domain-friendly alias for triggerId — the trigger id (a UUID). Use interchangeably in admin URLs.

string
triggerId
required
string
flowId

A schedule that runs a flow: the flow, at flowVersion.

string
>= 1 characters
flowVersion
string
>= 1 characters
agentId

A schedule that runs an agent: the agent, at agentVersion, else its version live for the schedule’s project (else the latest), as a run that names none.

string
>= 1 characters
agentVersion
string
>= 1 characters
improve

A schedule that starts improvement passes: on this agent, for this scope, when enough new trusted “no” judgments have come in (input: the threshold, the monthly cap and the pass options).

object
agentId
required
string
>= 1 characters
scope
required
One of: discriminator: kind

The agent’s default for the whole tenant.

object
kind
required
string
Allowed values: tenant
projectId

The schedule’s project: its runs are this project’s.

string format: uuid
owner

Who its runs act as: whoever registered it, until an admin takes it over (POST …/owner). Checked again at every fire.

object
kind
required
string
Allowed values: user service
id
required
string
displayName

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.

string
cronExpression
required

5- or 6-field cron expression (croner-compatible). 6-field enables second precision.

string
>= 1 characters
timezone

IANA timezone (e.g. UTC, America/New_York). Absent → UTC.

string
input

Static input handed to the run on every fire. Absent → {}.

catchUp

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.

string
Allowed values: latest skip
overlap

When an occurrence comes while the previous run of this schedule is still running: skip records the fire as skipped; allow starts another run.

string
Allowed values: skip allow
startingDeadlineSeconds

How late a fire may start and still count as on time; past it, catchUp applies.

integer
>= 1
label
required
string | null
status
required

Lifecycle status. Only active triggers fire. Tombstoned rows are excluded from every read path.

string
Allowed values: active paused
statusReason

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.

string
nextFireAt
required

Wall-clock time of the next scheduled fire. null on paused rows if the cron scheduler never re-armed.

string | null format: date-time
upcoming

The next occurrences, when the request asked for them (?upcoming=N).

Array<string>
lastFiredAt
required
string | null format: date-time
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
nextCursor
string
hasMore
required
boolean
Example
{
  "data": [
    {
      "improve": {
        "scope": {
          "kind": "tenant"
        }
      },
      "owner": {
        "kind": "user"
      },
      "catchUp": "latest",
      "overlap": "skip",
      "status": "active"
    }
  ]
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also