DOC-API-MODEL-schema-1ld0l8rmvg#overview
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.
Meaning and usage
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#meaning
See the definition above.
Usage profiles
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#fields
| Usage | Fields and validation |
|---|---|
| In responses | View fields |
In responses
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#response
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-scheduleidSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-scheduleidscheduleId | string | Optional | Server-assigned identifier of the scheduled job, prefixed with "sched_". |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-tenantidSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-tenantidtenantId | string | Optional | Identifier of the tenant that owns or scopes this record. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-projectidSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-projectidprojectId | string | Optional | Identifier of the project within the tenant that scopes this record. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-ownersubjectSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-ownersubjectownerSubject | string | Optional | Subject identifier of the owning user or service account. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-nameSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-namename | string | Optional | Human-readable name assigned to the scheduled job. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-descriptionSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-descriptiondescription | string | Optional | Human-readable explanation of the scheduled job. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-scheduletypeSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-scheduletypescheduleType | string (SCHEDULE_TYPE_CRON, SCHEDULE_TYPE_ONCE, SCHEDULE_TYPE_RECURRING_INTERVAL) or integer (int32) | Optional; explicit presence | Schedule type and expression. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-cronexpressionSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-cronexpressioncronExpression | string | Optional | Cron expression. Populated when schedule_type is SCHEDULE_TYPE_CRON. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-timezoneSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-timezonetimezone | string | Optional | IANA timezone for cron evaluation. Default "UTC". |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-scheduledatSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-scheduledatscheduledAt | string (date-time) | Optional | Exact fire time. Populated when schedule_type is SCHEDULE_TYPE_ONCE. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-intervalsecondsSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-intervalsecondsintervalSeconds | string (int64) | Optional | Interval between firings in seconds. Populated when schedule_type is SCHEDULE_TYPE_RECURRING_INTERVAL. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-targetSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-targettarget | ScheduleTarget | Optional | Destination and invocation settings for the scheduled job. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-stateSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-statestate | string (SCHEDULE_STATUS_ACTIVE, SCHEDULE_STATUS_PAUSED, SCHEDULE_STATUS_DELETED) or integer (int32) | Optional; explicit presence | Lifecycle status controlling whether the scheduled job can trigger. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-retrypolicySection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-retrypolicyretryPolicy | RetryPolicy | Optional | Attempt limits and backoff settings for the scheduled target. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-metadataSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-metadatametadata | Map from string to JSON value | Optional | Application-defined JSON metadata attached to the scheduled job. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-autopausethresholdSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-autopausethresholdautoPauseThreshold | string (int64) | Optional | See meaning below. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-externalidSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-externalidexternalId | 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_". |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-createdatSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-createdatcreatedAt | string (date-time) | Optional | Time at which the scheduled job was created. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-createdbysubjectSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-createdbysubjectcreatedBySubject | string | Optional | Subject identifier recorded when the schedule was created. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-updatedatSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-updatedatupdatedAt | string (date-time) | Optional | Time this record was most recently updated. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-updatedbysubjectSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-updatedbysubjectupdatedBySubject | string | Optional | Subject identifier recorded when the schedule was last updated. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-pausedatSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-pausedatpausedAt | string (date-time) | Optional | Time at which the schedule was paused. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-pausedbysubjectSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-pausedbysubjectpausedBySubject | string | Optional | Subject identifier recorded for the schedule pause. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-pausedreasonSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-pausedreasonpausedReason | string | Optional | Explanation recorded for the schedule pause. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-resumedatSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-resumedatresumedAt | string (date-time) | Optional | Time at which the schedule was most recently resumed. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-resumedbysubjectSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-resumedbysubjectresumedBySubject | string | Optional | Subject identifier recorded for the schedule resume. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-deletedatSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-deletedatdeletedAt | string (date-time) | Optional | Time at which the schedule was deleted. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-deletedbysubjectSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-deletedbysubjectdeletedBySubject | string | Optional | Subject identifier recorded for the schedule deletion. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-lasttriggeredatSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-lasttriggeredatlastTriggeredAt | string (date-time) | Optional | Time when the schedule was last triggered. Trigger and failure counters advance at most once per scheduled firing on its first attempt; retrying that firing does not inflate them. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-nexttriggeratSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-nexttriggeratnextTriggerAt | string (date-time) | Optional | Time calculated for the next scheduled trigger. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-triggercountSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-triggercounttriggerCount | string (int64) | Optional | Scheduled times that ran, cumulative for the schedule's whole life. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-failurecountSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-failurecountfailureCount | string (int64) | Optional | See meaning below. Pattern: ^-?\d+$. |
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#field-consecutivefailurecountSection ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-field-consecutivefailurecountconsecutiveFailureCount | string (int64) | Optional | See meaning below. Pattern: ^-?\d+$. |
autoPauseThreshold
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.
A stored threshold of 0 disables auto-pause; otherwise the threshold is from 3 through 100. The public create request uses 0 or omission to select the default of 10, and the public update request uses 0 or omission to leave the current threshold unchanged. These public requests do not provide a disable control.
failureCount
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.
consecutiveFailureCount
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.
Values of scheduleType
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-values-scheduletype
Expression format that determines when a scheduled job fires.
| Value | No. | Form | Meaning |
|---|---|---|---|
SCHEDULE_TYPE_CRON | 0 | Canonical | Fire according to the configured cron expression and timezone. For example, 0 9 * * 1-5 selects 09:00 on weekdays in that timezone. |
SCHEDULE_TYPE_ONCE | 1 | Canonical | Fire once at the configured scheduled timestamp. |
SCHEDULE_TYPE_RECURRING_INTERVAL | 2 | Canonical | Fire repeatedly at the configured interval in seconds. |
Values of state
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#response-values-state
Lifecycle condition that determines whether a scheduled job may trigger: active, paused, or deleted. This is separate from the outcome of an individual scheduled-job execution.
| Value | No. | Form | Meaning |
|---|---|---|---|
SCHEDULE_STATUS_ACTIVE | 0 | Canonical | The schedule is active and can trigger at its next matching time. |
SCHEDULE_STATUS_PAUSED | 1 | Canonical | The schedule is paused and does not trigger until resumed. |
SCHEDULE_STATUS_DELETED | 2 | Canonical | The schedule has been deleted; this is a schedule condition, not an execution outcome. |
Where used
Section ID: DOC-API-MODEL-schema-1ld0l8rmvg#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 ID: DOC-API-MODEL-schema-1ld0l8rmvg