AI Workforce OneHQDocs

Schedules

Schedules and their run history.

List schedules

GET/v1/schedules
Permission schedules:read
Query parameters
limitinteger

How many objects to return, 1 to 100. Default 20.

starting_afterstring

Return objects older than this id (the next page).

ending_beforestring

Return objects newer than this id (the previous page).

teamstring

Only schedules of this AI team.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

A page of schedules.

Other

An RFC 9457 problem.

Create a schedule

POST/v1/schedules
Permission schedules:write

A 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.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Body parameters
teamstringrequired
namestringrequired
promptstringrequired

The task, as you would type it. Refused with 422 validation_failed (the reason is in detail) 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 contains kr-run:, which HQ reserves for its own run marker.

timezonestringrequired

An IANA time zone, for example Europe/London.

frequencystringrequired

One of daily, specific_days, weekly, monthly, once.

days_of_weekarray of integer
day_of_monthinteger
datestring (date)

For once.

run_timestringrequired

HH:mm.

run_timesarray of string
target_sessionstring

Run in this existing session. Send exactly one of target_session or create_new_session true.

create_new_sessionboolean

Start a new session for each run. Send exactly one of target_session or create_new_session true.

on_stopped_sessionstring

One of restart, skip_notify.

run_withstring

With create_new_session only. One of personal, team_key.

enginestring

One of claude, codex.

enabledboolean

Returns a Schedule object.

Responses
201

The schedule.

Other

An RFC 9457 problem.

Get a schedule

GET/v1/schedules/{schedule_id}
Permission schedules:read
Path parameters
schedule_idstringrequired

A schedule id.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The schedule.

Other

An RFC 9457 problem.

Update a schedule

PATCH/v1/schedules/{schedule_id}
Permission schedules:write

Any 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.

Path parameters
schedule_idstringrequired

A schedule id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Body parameters
namestring
promptstring

The same rules as on create.

timezonestring
frequencystring

One of daily, specific_days, weekly, monthly, once.

days_of_weekarray of integer
day_of_monthinteger
datestring
run_timestring
run_timesarray of string
target_sessionstring

Switches the schedule to run in this existing session (turns create_new_session off).

create_new_sessionboolean

true switches the schedule to a new session for each run (clears target_session).

on_stopped_sessionstring

One of restart, skip_notify.

run_withstring

One of personal, team_key.

enginestring

One of claude, codex.

enabledboolean

Returns a Schedule object.

Responses
200

The schedule.

Other

An RFC 9457 problem.

Delete a schedule

DELETE/v1/schedules/{schedule_id}
Permission schedules:write
Path parameters
schedule_idstringrequired

A schedule id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
204

Deleted.

Other

An RFC 9457 problem.

List a schedule's runs

GET/v1/schedules/{schedule_id}/runs
Permission schedules:read

Newest first. Pages forward with starting_after.

Path parameters
schedule_idstringrequired

A schedule id.

Query parameters
limitinteger

How many objects to return, 1 to 100. Default 20.

starting_afterstring

Return objects older than this id (the next page).

resultstring

Only runs with this result. One of success, failed, skipped.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

A page of runs.

Other

An RFC 9457 problem.

Run a schedule now

POST/v1/schedules/{schedule_id}/runs
Permission schedules:run

Fires 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.

Path parameters
schedule_idstringrequired

A schedule id.

Headers
Idempotency-Keystringrequired

Required 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, 409 idempotency_in_progress.

HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
202

The run started, or was queued.

Other

An RFC 9457 problem.

Get a schedule run

GET/v1/schedules/{schedule_id}/runs/{run_id}
Permission schedules:read
Path parameters
schedule_idstringrequired

A schedule id.

run_idstringrequired

A schedule run id.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The run.

Other

An RFC 9457 problem.

Enable a schedule

POST/v1/schedules/{schedule_id}/enable
Permission schedules:write

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.

Path parameters
schedule_idstringrequired

A schedule id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The schedule, enabled.

Other

An RFC 9457 problem.

Disable a schedule

POST/v1/schedules/{schedule_id}/disable
Permission schedules:write
Path parameters
schedule_idstringrequired

A schedule id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The schedule, disabled.

Other

An RFC 9457 problem.

Move a schedule to its session's owner

POST/v1/schedules/{schedule_id}/move_to_session_owner
Permission schedules:write

A 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).

Path parameters
schedule_idstringrequired

A schedule id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The schedule, now running as the session's owner.

Other

An RFC 9457 problem.

Objects

Schedule

Attributes
objectstring
idstring
teamstring
namestring
enabledboolean
cronstring
timezonestring
frequencystring
run_timesarray of string
promptstring
target_sessionstring or null
create_new_sessionboolean
on_stopped_sessionstring
run_withstring or null
enginestring or null
last_run_atstring or null
last_run_statusstring or null
next_run_atstring or null
created_atstring (date-time)
created_byUserRef

ScheduleRun

Attributes
objectstring
idstring
schedulestring
sessionstring or null
statusstring
outcomestring or null
started_atstring (date-time)
completed_atstring or null
tokens_usedinteger
cost_usdnumber
triggered_byUserRef

ScheduleRunRequest

Attributes
objectstring
queuedboolean
runstring or null

The run id (poll GET /schedules/{schedule_id}/runs/{run_id}).

sessionstring or null