Schedule
Schedule is the canonical representation of a scheduled job.
Creating any schedule type returns the Schedule resource directly, with the same shape used by get, pause and resume operations.
triggerCount: Cumulative firings.
failureCount: Cumulative failed first attempts; a later successful retry does not erase the earlier failure.
consecutiveFailureCount: Current sequence of failed firings; a successful attempt resets it. This counter drives auto-pause.
Zero-valued counters can be omitted. Nonzero 64-bit counters are decimal JSON strings; preserve their integer precision.
Usage profiles
| Usage | Fields and validation |
|---|---|
| In responses | View fields |
In responses
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
scheduleId | string | Optional | Server-assigned identifier of the scheduled job, prefixed with "sched_". |
tenantId | string | Optional | Identifier of the tenant that owns or scopes this record. |
projectId | string | Optional | Identifier of the project within the tenant that scopes this record. |
ownerSubject | string | Optional | Subject identifier of the owning user or service account. |
name | string | Optional | Human-readable name assigned to the scheduled job. |
description | string | Optional | Human-readable explanation of the scheduled job. |
scheduleType | string (SCHEDULE_TYPE_CRON, SCHEDULE_TYPE_ONCE, SCHEDULE_TYPE_RECURRING_INTERVAL) or integer (int32) | Optional | Schedule type and expression. |
cronExpression | string | Optional | Cron expression. Populated when schedule_type is SCHEDULE_TYPE_CRON. |
timezone | string | Optional | IANA timezone for cron evaluation. Default "UTC". |
scheduledAt | string (date-time) | Optional | Exact fire time. Populated when schedule_type is SCHEDULE_TYPE_ONCE. |
intervalSeconds | integer (int32) | Optional | Interval between firings in seconds. Populated when schedule_type is SCHEDULE_TYPE_RECURRING_INTERVAL. Minimum: -2147483648. Maximum: 2147483647. |
target | ScheduleTarget | Optional | Destination and invocation settings for the scheduled job. |
state | string (SCHEDULE_STATUS_ACTIVE, SCHEDULE_STATUS_PAUSED, SCHEDULE_STATUS_DELETED) or integer (int32) | Optional | Lifecycle status controlling whether the scheduled job can trigger. |
retryPolicy | RetryPolicy | Optional | Attempt limits and backoff settings for the scheduled target. |
metadata | Map from string to JSON value | Optional | Application-defined JSON metadata attached to the scheduled job. |
autoPauseThreshold | integer (int32) | Optional | If consecutive_failure_count reaches this threshold the job is auto-paused (state PAUSED, paused_by_subject "system:auto-pause"). It is compared against consecutive_failure_count, NOT failure_count. failure_count is cumulative for the schedule's whole life, so a healthy schedule that collects scattered failures over months would eventually exceed any threshold and pause itself forever. 0 disables auto-pause; otherwise must be in the range [3, 100]. Default 10. Minimum: -2147483648. Maximum: 2147483647. |
externalId | string | Optional | Client-supplied external id. Echoed back when set; empty otherwise. Optional, immutable, unique within (tenant_id, project_id) among live schedules. Never starts with the reserved system-id prefix "sched_". |
createdAt | string (date-time) | Optional | Time at which the scheduled job was created. |
createdBySubject | string | Optional | Subject identifier recorded when the schedule was created. |
updatedAt | string (date-time) | Optional | Time this record was most recently updated. |
updatedBySubject | string | Optional | Subject identifier recorded when the schedule was last updated. |
pausedAt | string (date-time) | Optional | Time at which the schedule was paused. |
pausedBySubject | string | Optional | Subject identifier recorded for the schedule pause. |
pausedReason | string | Optional | Explanation recorded for the schedule pause. |
resumedAt | string (date-time) | Optional | Time at which the schedule was most recently resumed. |
resumedBySubject | string | Optional | Subject identifier recorded for the schedule resume. |
deletedAt | string (date-time) | Optional | Time at which the schedule was deleted. |
deletedBySubject | string | Optional | Subject identifier recorded for the schedule deletion. |
lastTriggeredAt | string (date-time) | Optional | Time when the schedule was last triggered. |
nextTriggerAt | string (date-time) | Optional | Time calculated for the next scheduled trigger. |
triggerCount | string (int64) | Optional | Scheduled times that ran, cumulative for the schedule's whole life. Pattern: ^-?\d+$. |
failureCount | string (int64) | Optional | Scheduled times whose first attempt failed, cumulative for the schedule's whole life. A firing that fails on attempt 1 and succeeds on retry still counts here — a failure was observed. This counter does NOT drive auto-pause. See consecutive_failure_count. Pattern: ^-?\d+$. |
consecutiveFailureCount | string (int64) | Optional | Current run of consecutive failed firings. This is the counter auto_pause_threshold is compared against. Incremented when a firing's first attempt fails; reset to 0 as soon as any attempt of any firing succeeds. So a firing that fails on attempt 1 and succeeds on retry has net zero effect here while still advancing failure_count — the target recovered, so the run is over. A non-success terminal outcome counts as a failure, including a firing cancelled on a terminal 4xx. Pattern: ^-?\d+$. |
Values of scheduleType
Expression format that determines when a scheduled job fires.
| Value | No. | Form | Meaning |
|---|---|---|---|
SCHEDULE_TYPE_CRON | 1 | Canonical | Fire according to the configured cron expression and timezone. |
SCHEDULE_TYPE_ONCE | 2 | Canonical | Fire once at the configured scheduled timestamp. |
SCHEDULE_TYPE_RECURRING_INTERVAL | 3 | Canonical | Fire repeatedly at the configured interval in seconds. |
Values of state
Lifecycle condition that determines whether a scheduled job may trigger.
| Value | No. | Form | Meaning |
|---|---|---|---|
SCHEDULE_STATUS_ACTIVE | 1 | Canonical | The schedule is active and can trigger at its next matching time. |
SCHEDULE_STATUS_PAUSED | 2 | Canonical | The schedule is paused and does not trigger until resumed. |
SCHEDULE_STATUS_DELETED | 3 | Canonical | The schedule has been deleted; this is a schedule condition, not an execution outcome. |
Where used
| Reference | Relationship |
|---|---|
| Create a scheduled job | POST /api/v1/scheduler/create-job |
| Get a scheduled job | POST /api/v1/scheduler/get-job |
| List scheduled jobs | POST /api/v1/scheduler/list-jobs |
| Pause a scheduled job | POST /api/v1/scheduler/pause-job |
| Resume a scheduled job | POST /api/v1/scheduler/resume-job |
| Update a scheduled job | POST /api/v1/scheduler/update-job |
Download the public reference contract.
Document: DOC-API-MODEL-schedule.