Skip to main content
POST
cURL
Jobs are enabled by default. After creation, the schedule invokes models and tools and saves job data and results to TOS. Check the message, schedule, and access rights before submitting. Set enabled to false to save a job without starting its schedule
Requires a Harness Runtime deployed with AgentKit CLI 0.54.0 and scheduled tasks enabled Exactly one of schedule.cron and schedule.at must be non-null. For an enabled one-time task, at must include a timezone offset and lie in the future Use a stable idempotency_key when retrying creation. Identical requests with the same key return the same task and HTTP 201; different input with that key returns 422. Omitting the key creates a new task on every request harness uses the task override structure shown on this page. Omitted fields inherit deployed settings. Each execution uses a separate session, and its final output is persisted in TOS

Authorizations

Authorization
string
header
required

Runtime access credential for a service-authenticated Harness, such as a Runtime API key; shared OAuth deployments do not support background scheduled tasks

Body

application/json

Request to create a task; undeclared fields are rejected

name
string
required

Task name, 1–128 characters

Required string length: 1 - 128
prompt
string
required

Message sent to the agent on each execution, 1–65536 characters

Required string length: 1 - 65536
schedule
Schedule · object
required

Trigger schedule

harness
JobHarnessOverrides · object | null

Task-specific overrides using the AgentKit CLI deployment format, such as mcp_servers

enabled
boolean
default:true

Whether future scheduling is enabled

timeout_seconds
integer
default:1800

Execution timeout in seconds; timeout records a failed execution without automatically retrying it

Required range: 1 <= x <= 10800
misfire_policy
enum<string>
default:latest

latest runs the most recent missed occurrence; skip runs it only within the grace period. Neither policy replays every missed occurrence

Available options:
latest,
skip
misfire_grace_seconds
integer
default:120

Maximum lateness in seconds allowed by the skip policy

Required range: 0 <= x <= 86400
idempotency_key
string | null

Optional idempotency key. The same key and request return the same task; reusing a key with different input returns 422. Omission creates a new task each time

Required string length: 1 - 128

Response

Success; repeated identical idempotent requests also return 201

name
string
required

Task name, 1–128 characters

Required string length: 1 - 128
prompt
string
required

Message sent to the agent on each execution, 1–65536 characters

Required string length: 1 - 65536
schedule
Schedule · object
required

Trigger schedule

harness
CronjobHarnessPublicOverrides · object | null
required

Settings applied to each execution of this task; explicit fields override the deployed agent and omitted fields inherit it

enabled
boolean
required

Whether future scheduling is enabled

timeout_seconds
integer
required

Execution timeout in seconds; timeout records a failed execution without automatically retrying it

Required range: 1 <= x <= 10800
misfire_policy
enum<string>
required

latest runs the most recent missed occurrence; skip runs it only within the grace period. Neither policy replays every missed occurrence

Available options:
latest,
skip
misfire_grace_seconds
integer
required

Maximum lateness in seconds allowed by the skip policy

Required range: 0 <= x <= 86400
cronjob_id
string
required

Owning task ID

Pattern: ^[a-f0-9]{32}$
revision
integer
required

Task revision number

created_at
string<date-time>
required

Task creation time in UTC

updated_at
string<date-time>
required

Most recent task update time in UTC

next_run_at
string<date-time> | null
required

Next scheduled occurrence in UTC; null when no future occurrence remains

active
object | null
required

The queued or running execution, or an execution whose final result is still being persisted

last_run
object | null
required

Summary of the most recently persisted historical execution

Last modified on September 19, 2026