Skip to content
Kindgi

Fetch one version of a schedule

View as Markdown
GET
/v1/schedules/{triggerId}/versions/{version}
curl --request GET \
  --url https://example.com/v1/schedules/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/versions/1 \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
triggerId
required
string format: uuid

TriggerId — the trigger id (a UUID).

version
required
integer
>= 1

The version’s number: 1 for the trigger’s first, one more for each after.

Responses

Section titled “Responses”

200

Section titled “200”

The version.

Media typeapplication/json

One version of a schedule: what it was from createdAt until the next. A fire’s run uses the newest when it starts, and keeps it.

object
scheduleId
required

The same id as triggerId.

string
triggerId
required
string
version
required

Counts from 1, one more for each version.

integer
>= 1
createdAt
required
string format: date-time
createdBy

Who made the change, as audit records name an actor (user:<id>, service_account:<id>, …). Absent on a version the runtime made (first-fire, unversioned-edit, pin).

string
cause
required

What made the version: register (the trigger’s first), edit (a change to it), owner (a take-over to another owner), first-fire (the runtime’s, at the first fire of a trigger from before versions, or a mail trigger’s first look at its mailbox), unversioned-edit (the runtime’s, at a fire or a mail trigger’s look at its mailbox, or just before an edit or take-over, when the trigger’s definition isn’t its newest version’s, as when a release from before versions changed it during an upgrade) or pin (the runtime’s, when it fixed a mail trigger to the one connection it could use).

string
Allowed values: register edit owner first-fire unversioned-edit pin
definition
required

What a schedule’s version runs, when and as whom, as its record names them, and never its state (status, next or last fire). The versions keep every input the trigger has had, so a secret pasted into its input stays in an earlier version after you edit it out: rotate it.

object
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 pinned 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 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
agentId
required
string
>= 1 characters
projectId

The schedule’s own project. Absent from older servers, and on a schedule registered for a workspace or an org before Improve schedules worked in a project: its fires are refused until its target is saved with the schedule’s project.

string format: uuid
projectId
required

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

string format: uuid
owner
required

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
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
isProjectAccount

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.

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

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 workspace’s suspension isn’t caught up either way: once the workspace is restored, a schedule that’s on fires next at its first occurrence after the restore.

string
Allowed values: latest skip
overlap
required

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
required

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

integer
>= 1
label
required
string | null
toolsAllowedUnattended

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 workspace’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.

Array<string>
<= 100 items unique items
Example
{
  "cause": "register",
  "definition": {
    "owner": {
      "kind": "user",
      "isProjectAccount": true
    },
    "catchUp": "latest",
    "overlap": "skip"
  }
}

400

Section titled “400”

version isn’t a positive integer (bad-input, details.field).

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"
  }
}

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"
  }
}

404

Section titled “404”

No cron trigger with that id (trigger-not-found), or it has no version with that number (trigger-version-not-found).

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"
  }
}

503

Section titled “503”

The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.

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