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. |
initial_events_version | integer | Read-only input content version, starting at 1. See Input version. |
resources | array | Schedule-specific file configuration, sorted by file_id; [] when unconfigured. See File resources for the structure and application rules. |
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.
File resources
When creating or updating a Schedule, specify files in the top-level resources array, using the same format as Session and Batch file resources. First upload a File to obtain a file_id, then reference a Forward File that the current caller can access under the Schedule's Identity.
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Currently, only file is supported. |
file_id | string | Yes | File ID returned by the Files API. Treat it as an opaque string; no fixed prefix is required. It must not be empty or contain control characters. |
mount_path | string | No | File path in the Agent container. An explicit path must be a canonical absolute path, must not be / or contain control characters, and must not exceed 1024 bytes. |
enabled are not accepted. Specify at most 100 files. An array must not contain duplicate file_id values or explicitly assign the same mount path to different files. The API does not accept a top-level files parameter.
An omitted or empty-string mount_path uses /data/workspace/<filename>; explicitly specify different paths for files with the same name. If the same file is already configured in the Template / Identity Config, omitting the Schedule path preserves the inherited path.
Create and update
Request resources | Create Schedule | Update Schedule |
|---|---|---|
| Omitted | No dedicated files are configured. | Preserve the existing configuration. |
null or [] | No dedicated files are configured. | Clear all dedicated file configuration. |
| Nonempty array | Configure the files in the array. | Replace the entire dedicated file configuration, without merging individual items. |
resources array, including [] for older Schedules. It represents only the Schedule's own configuration, without files inherited from the Template / Identity Config; omitted mount paths are not filled with runtime paths here. Changing resources does not increment initial_events_version, which describes only initial_events.
Inheritance and application timing
At execution time, Schedule files are merged with files from the current Template / Identity Config. The same file_id is deduplicated: reuse is allowed when the Schedule omits the path or explicitly uses the inherited path; a different explicit path causes a conflict. Different files cannot occupy the same path. Conflicts detectable only after merging inherited configuration are reported during execution, before the task message is sent.
Both new_session and reuse_session support file configuration. Each execution attempt selects its Schedule-specific resources before creating the Session or sending the task. Send retries and recovery within the same attempt reuse the selected dedicated file configuration; a new attempt can select updated configuration. Updates do not interrupt the current execution. Subsequent executions apply the selected additions, removals, and path changes, including synchronization when reusing a Session. Files inherited from the Template / Identity Config are outside this snapshot and continue to refresh from the current configuration.
Clearing Schedule files does not remove inherited files or change the Template / Identity Config. Mounting files does not automatically insert their contents into initial_events; the task can read files by mount path in its message, for example, Read /data/news-sources.csv and summarize its contents.
File deletion restrictions
If an unarchived Schedule, including a paused Schedule, references a file, Delete File returns HTTP 409. Updating or clearing the file configuration, or archiving the Schedule, releases that configuration reference. Files selected by a Run that has not reached a terminal state remain protected until the Run ends. References from other Templates / Identity Configs or Sessions may also continue to prevent deletion.
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. |
initial_events_version | integer (optional) | Version of the input selected for the current execution attempt; omitted when input has not been selected or cannot be confirmed. See Input version. |
initial_events | array (optional) | Only when retrieving a single Run with include_initial_events=true: the bound input snapshot for the current attempt, omitted if unknown. See Query input snapshot. |
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.
Identity state and scheduling
While an Identity is disabled, no new Schedule executions start, and Runs that have not started may be recorded as skipped. Accepted executions and result delivery finish naturally. After re-enabling, recurring tasks resume at future trigger times without replaying missed triggers. Expired one-time triggers retain a skipped Run and are archived normally. Manually paused, archived, or deleted Schedules are not restored by enabling the Identity. See Enable an identity.
Input version
initial_events_version is maintained by the server and must not be supplied in create or update requests. A new Schedule starts at 1. The version increments only when the normalized initial_events content actually changes. Submitting identical content or changing resources, the name, execution policy, or trigger policy does not increment it. Restoring previously used content creates a new version. For existing Schedules, the current input starts at 1; historical versions are not reconstructed.
A Run is not bound to input when it is created. Before sending input for the first time in an attempt, the executor binds the matching content and version to the Run. Send retries and recovery within the same attempt reuse that binding; a new attempt may select updated input. Interpret the version together with attempt: its presence means that input has been selected, not that the runtime has received it or executed it successfully.
The field is omitted for pending or skipped Runs that have not selected input, and for historical Runs whose execution input cannot be confirmed. An unknown version is not returned as 0 and must not be filled with the current Schedule version. Clients should tolerate the added field and treat a missing version as unknown.
After creating or updating a Schedule, integrations can store the mapping between schedule_id, initial_events_version, and input content, then correlate execution input using the version in a Run or Webhook callback. The current Schedule returns the latest configuration, which may differ from that of a Run that has already started.
Retrieve the selected input with Get schedule run and include_initial_events=true, without relying on the current Schedule configuration.
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. |