Shared Schedule and Schedule Run response schemas for the Forward Schedule API.
Schedule object
Create, get, list, update, archive, pause, and unpause endpoints return this structure.
| Field | Type | Description |
|---|---|---|
id | string | Schedule ID, prefixed with sched_. |
source | string | Authoritative creation method, currently api or tool. See Creation source. |
source_session_id | string | null | Originating Session. null for api; a nonempty sess_* for tool. |
identity_id | string | Forward Identity ID that owns the Schedule. |
template_id | string | Forward Template ID used for execution. |
name | string | Schedule name. |
description | string | Schedule description; an empty string when unset. |
status | string | active or paused; archive state is expressed by archived_at. |
paused_reason | object | null | Reason for pausing; null when not paused. |
initial_events | array | Initial events injected into each execution. |
execution | object | Execution policy. See Execution policy. |
trigger_policy | object | Trigger policy. See Trigger policy. |
environment_id | string | Execution environment ID. |
sinks | array | Result delivery targets; [] when none are configured. |
metadata | object | Caller-provided business metadata. |
archived_at | string | null | Archive timestamp in RFC 3339 format; null when not archived. |
created_at | string | Creation timestamp in RFC 3339 format. |
updated_at | string | Last update timestamp in RFC 3339 format. |
Execution policy
| Field | Type | Description |
|---|---|---|
session_mode | string | new_session or reuse_session. |
max_concurrent_runs | integer | Maximum concurrent Runs for one Schedule. |
max_attempts | integer | Maximum attempts for one Run, currently 1 or 2. |
timeout_ms | integer | Timeout per attempt in milliseconds. |
Trigger policy
| Field | Type | Description |
|---|---|---|
type | string | cron, once, interval, or manual. |
expression | string | Trigger expression; empty or omitted for manual. |
timezone | string | IANA timezone; empty or omitted when not applicable. |
start_at | string | Optional execution window start in RFC 3339 format. |
stop_at | string | Optional execution window end in RFC 3339 format. |
upcoming_runs_at | array | Upcoming trigger times in UTC ISO 8601 format; currently [] or at most one timestamp. |
last_run_at | string | null | Most recent trigger time. |
sinks.
Schedule Run object
Run, get Run, and list Runs endpoints return this structure.
| Field | Type | Description |
|---|---|---|
id | string | Schedule Run ID, prefixed with srun_. |
source | string | Authoritative creation method of the parent Schedule, currently api or tool. See Creation source. |
source_session_id | string | null | Originating Session of the parent Schedule. |
schedule_id | string | Parent Schedule ID. |
identity_id | string | Forward Identity ID. |
template_id | string | Forward Template ID. |
session_id | string | null | Session created or used for this execution. |
status | string | pending, running, completed, failed, or skipped. |
trigger_context | object | How this Run was triggered. See Trigger Context. |
error | object | null | Structured error for a failed or skipped Run. |
result_payload | string | null | Main execution text result. |
error_message | string | null | Display-friendly error message; structured details remain in error. |
push_sink | string | null | Sink type used for this IM delivery; null when not configured. |
push_status | string | IM delivery status: pending, succeeded, failed, or skipped. |
push_finished_at | string | null | IM delivery end time. |
attempt | integer | Current or final attempt number, starting at 1. |
triggered_at | string | Trigger timestamp in RFC 3339 format. |
started_at | string | null | Execution start timestamp in RFC 3339 format. |
completed_at | string | null | Execution end timestamp in RFC 3339 format. |
duration_ms | integer | null | Execution duration in milliseconds. |
created_at | string | Record creation timestamp in RFC 3339 format. |
status and IM delivery push_status are independent. When the Schedule has execution.max_attempts=2, the same Run may ultimately return attempt=2.
Creation source
source and source_session_id are read-only fields that are always present in complete v1/v2 Schedule and Schedule Run responses.
source | source_session_id | Meaning |
|---|---|---|
api | null | Created through the public Schedule API. |
tool | Nonempty sess_* | Created through a Forward managed tool; identifies the interactive Session that initiated the creation tool call. |
metadata.source is mutable business metadata and does not represent the authoritative source.
A Schedule Run inherits its parent Schedule's source, regardless of whether this Run was triggered manually or automatically, or whether sinks are configured. This also applies to historical Runs and Runs of archived Schedules. The Run's session_id identifies its execution Session; trigger_context.type identifies how this Run was triggered. The originating Session does not indicate an execution binding for reuse_session, and internal origin-result delivery targets are not exposed as the public source.
The source fields are backward-compatible JSON additions; clients should tolerate unknown fields. After service deployment, query responses for historical Schedules and Runs also return these fields without a data backfill.
Trigger Context
type | Description |
|---|---|
schedule | Automatically triggered by the Schedule trigger policy; includes scheduled_at. |
manual | Manually triggered through the Run Schedule endpoint. |
Run Error
error may be returned when status=failed or status=skipped; it is null when status=completed.
error.type | Description |
|---|---|
concurrency_limit_reached | The Schedule has reached its concurrent Run limit. This trigger is recorded but is not executed. |
session_creation_failed | Creating or binding a Forward Session failed. |
execution_failed | Template execution failed. |