Schedules
Schedules and their run history.
List schedules
/v1/schedulesschedules:readlimitintegerHow many objects to return, 1 to 100. Default 20.
starting_afterstringReturn objects older than this id (the next page).
ending_beforestringReturn objects newer than this id (the previous page).
teamstringOnly schedules of this AI team.
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a list of Schedule objects.
200A page of schedules.
OtherAn RFC 9457 problem.
Create a schedule
/v1/schedulesschedules:writeA schedule runs as the member the user key acts as (a service key cannot create one yet).
Pointing it at a session that runs on someone else's personal login is refused. Never a
prompt that would run as a command: see prompt for what is refused.
Schedules always continue the session's conversation so Claude keeps its context. Resuming a long conversation uses part of your Claude usage limit.
On an AI team that turned on Protected files, a Codex schedule needs files:protected.read and files:protected.write on the key and its person: 403 protected_files_shell otherwise.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
teamstringrequirednamestringrequiredpromptstringrequiredThe task, as you would type it. Refused with
422 validation_failed(the reason is indetail) when it starts with/,!or#(a command, not a task), when it contains a control character (tabs and line breaks are fine), or when it containskr-run:, which HQ reserves for its own run marker.timezonestringrequiredAn IANA time zone, for example Europe/London.
frequencystringrequiredOne of
daily,specific_days,weekly,monthly,once.days_of_weekarray of integerday_of_monthintegerdatestring (date)For
once.run_timestringrequiredHH:mm.
run_timesarray of stringtarget_sessionstringRun in this existing session. Send exactly one of target_session or create_new_session true.
create_new_sessionbooleanStart a new session for each run. Send exactly one of target_session or create_new_session true.
on_stopped_sessionstringOne of
restart,skip_notify.run_withstringWith create_new_session only. One of
personal,team_key.enginestringOne of
claude,codex.enabledboolean
Returns a Schedule object.
201The schedule.
OtherAn RFC 9457 problem.
Get a schedule
/v1/schedules/{schedule_id}schedules:readschedule_idstringrequiredA schedule id.
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a Schedule object.
200The schedule.
OtherAn RFC 9457 problem.
Update a schedule
/v1/schedules/{schedule_id}schedules:writeAny of the create fields but the team. A user key only.
On an AI team that turned on Protected files, a Codex schedule's edit needs files:protected.read and files:protected.write on the key and its person: 403 protected_files_shell otherwise.
schedule_idstringrequiredA schedule id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
namestringpromptstringThe same rules as on create.
timezonestringfrequencystringOne of
daily,specific_days,weekly,monthly,once.days_of_weekarray of integerday_of_monthintegerdatestringrun_timestringrun_timesarray of stringtarget_sessionstringSwitches the schedule to run in this existing session (turns create_new_session off).
create_new_sessionbooleantrue switches the schedule to a new session for each run (clears target_session).
on_stopped_sessionstringOne of
restart,skip_notify.run_withstringOne of
personal,team_key.enginestringOne of
claude,codex.enabledboolean
Returns a Schedule object.
200The schedule.
OtherAn RFC 9457 problem.
Delete a schedule
/v1/schedules/{schedule_id}schedules:writeschedule_idstringrequiredA schedule id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
204Deleted.
OtherAn RFC 9457 problem.
List a schedule's runs
/v1/schedules/{schedule_id}/runsschedules:readNewest first. Pages forward with starting_after.
schedule_idstringrequiredA schedule id.
limitintegerHow many objects to return, 1 to 100. Default 20.
starting_afterstringReturn objects older than this id (the next page).
resultstringOnly runs with this result. One of
success,failed,skipped.
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a list of ScheduleRun objects.
200A page of runs.
OtherAn RFC 9457 problem.
Run a schedule now
/v1/schedules/{schedule_id}/runsschedules:runFires the schedule's stored prompt now. 202 with the run once it exists (it continues on its
own), or queued: true when the plan queues runs while every session slot is busy; 409
naming why a run was skipped. Requires an Idempotency-Key.
On an AI team that turned on Protected files, a Codex run needs files:protected.read and files:protected.write on the key and its person: 403 protected_files_shell otherwise. A Codex run whose schedule's author lacks them is skipped: 409 protected_files_shell.
schedule_idstringrequiredA schedule id.
Idempotency-KeystringrequiredRequired here. The same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422; while the first request is still running, 409idempotency_in_progress.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a ScheduleRunRequest object.
202The run started, or was queued.
OtherAn RFC 9457 problem.
Get a schedule run
/v1/schedules/{schedule_id}/runs/{run_id}schedules:readschedule_idstringrequiredA schedule id.
run_idstringrequiredA schedule run id.
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a ScheduleRun object.
200The run.
OtherAn RFC 9457 problem.
Enable a schedule
/v1/schedules/{schedule_id}/enableschedules:writeOn an AI team that turned on Protected files, a Codex schedule needs files:protected.read and files:protected.write on the key and its person: 403 protected_files_shell otherwise.
schedule_idstringrequiredA schedule id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a Schedule object.
200The schedule, enabled.
OtherAn RFC 9457 problem.
Disable a schedule
/v1/schedules/{schedule_id}/disableschedules:writeschedule_idstringrequiredA schedule id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a Schedule object.
200The schedule, disabled.
OtherAn RFC 9457 problem.
Move a schedule to its session's owner
/v1/schedules/{schedule_id}/move_to_session_ownerschedules:writeA schedule that reuses a session runs on the Claude login of the person it runs as
(created_by). When the session is reassigned to someone else, the schedule stops
running until it is moved. This moves it to the session's current owner: from then on it
runs on their Claude login, and created_by names them.
It only ever moves to the session's current owner, so it takes no body. Over the API only
the session's owner can do this, with their own user key: it puts the schedule on their
own Claude login. Organization owners and admins and team owners move a teammate's
schedule in HQ. A schedule that already runs as the owner is returned unchanged (safe to
retry). Schedules that start a new session each run, and schedules on the team's API key,
cannot be moved, and a schedule never moves to an owner who can't manage schedules on the
team (409 owner_cannot_manage_schedules).
schedule_idstringrequiredA schedule id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a Schedule object.
200The schedule, now running as the session's owner.
OtherAn RFC 9457 problem.
Objects
Schedule
objectstringidstringteamstringnamestringenabledbooleancronstringtimezonestringfrequencystringrun_timesarray of stringpromptstringtarget_sessionstring or nullcreate_new_sessionbooleanon_stopped_sessionstringrun_withstring or nullenginestring or nulllast_run_atstring or nulllast_run_statusstring or nullnext_run_atstring or nullcreated_atstring (date-time)created_byUserRef
ScheduleRun
objectstringidstringschedulestringsessionstring or nullstatusstringoutcomestring or nullstarted_atstring (date-time)completed_atstring or nulltokens_usedintegercost_usdnumbertriggered_byUserRef
ScheduleRunRequest
objectstringqueuedbooleanrunstring or nullThe run id (poll GET /schedules/{schedule_id}/runs/{run_id}).
sessionstring or null