Skip to main content
POST
Create Run Schedule

Path Parameters

agent_id
string
required

Body

application/json

Request body for creating a scheduled agent run.

name
string
required

Human-readable name, unique among active schedules for the agent.

Required string length: 1 - 64
Pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$
initial_input
ScheduleInitialInput · object
required

The first input delivered to each created task.

description
string | null

Optional description of what this schedule does.

cron_expression
string | null

Cron expression for the cadence (e.g. '0 17 * * MON-FRI'). Mutually exclusive with interval_seconds.

interval_seconds
integer | null

Interval cadence in seconds. Mutually exclusive with cron_expression.

Required range: x >= 1
timezone
string
default:UTC

IANA timezone the cron expression is evaluated in (e.g. 'America/New_York').

start_at
string<date-time> | null

When the schedule should start being active.

end_at
string<date-time> | null

When the schedule should stop being active.

paused
boolean
default:false

Whether to create the schedule in a paused state.

task_params
Task Params · object | null

Resolved config forwarded as task params at fire time.

task_metadata
Task Metadata · object | null

Metadata copied onto each created task at fire time.

Response

Successful Response

Response model describing a scheduled agent run.

id
string
required

The unique identifier of the run schedule.

agent_id
string
required

The agent this schedule belongs to.

name
string
required

Human-readable schedule name.

initial_input
ScheduleInitialInput · object
required

The initial input.

initial_input_method
string
required

Delivery method, inferred from the agent's ACP type.

description
string | null

Optional description.

cron_expression
string | null

Cron cadence, if cron-based.

interval_seconds
integer | null

Interval cadence in seconds, if interval-based.

timezone
string
default:UTC

Timezone the cron expression is evaluated in.

start_at
string<date-time> | null

Schedule activation time.

end_at
string<date-time> | null

Schedule deactivation time.

paused
boolean
default:false

Whether the schedule is paused.

task_params
Task Params · object | null

Task params at fire time.

task_metadata
Task Metadata · object | null

Task metadata at fire time.

creator_principal
ScheduleCreatorPrincipal · object | null

Credential-free creator identity.

created_at
string<date-time> | null

When the schedule was created.

updated_at
string<date-time> | null

When the schedule was updated.

state
enum<string>
default:ACTIVE

Live schedule state from Temporal.

Available options:
ACTIVE,
PAUSED
next_action_times
string<date-time>[]

Upcoming scheduled fire times.

live_data_available
boolean | null

Whether requested live Temporal fields were retrieved successfully. Null when live enrichment was not requested.

skipped_action_times
string<date-time>[]

Skipped one-off scheduled fire times.

last_action_time
string<date-time> | null

When the schedule last fired.

num_actions_taken
integer
default:0

Number of times the schedule has fired.