> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a scheduled task
> Create a recurring or one-time task and return its definition and state
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](/productions/api-reference/preview/en/harness-runtime/cronjobs/overview)
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
## OpenAPI
````yaml productions/api-reference/openapi/en/harness-runtime.json POST /harness/cronjobs
openapi: 3.1.0
info:
title: Harness Runtime
version: agentkit-cli 0.54.0 / SDK 0.8.0 / ADK 2.2.0
description: >-
Harness Runtime deployed by AgentKit CLI 0.54.0, verified with VeADK 1.0.8,
AgentKit SDK 0.8.0, and Google ADK 2.2.0; scheduled tasks require separate
enablement
servers:
- url: http://localhost:8000
description: Local server
security:
- {}
- RuntimeBearer: []
tags:
- name: Service and applications
- name: Sessions
- name: Agent execution
- name: Artifacts
- name: Memory
- name: Evaluation · development server
- name: Debugging · development server
- name: Compatibility endpoints
- name: Harness cronjobs
paths:
/harness/cronjobs:
post:
tags:
- Harness Runtime cronjobs
summary: Create a scheduled task
description: Create a recurring or one-time task and return its definition and state
operationId: harness_cronjob_create
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CronjobCreateRequest'
examples:
recurring:
summary: Recurring task
value:
name: daily-report
prompt: Summarize recent activity
schedule:
cron: 0 9 * * *
timezone: Asia/Shanghai
idempotency_key: daily-report-v1
one-time:
summary: One-time task; use a future time when sending
value:
name: one-time-report
prompt: Summarize recent activity
schedule:
at: '2026-10-01T09:00:00+08:00'
idempotency_key: one-time-report-v1
overrides:
summary: Task overrides; replace the MCP URL and credential
value:
name: daily-report
prompt: Summarize recent activity
schedule:
cron: 0 9 * * *
timezone: Asia/Shanghai
idempotency_key: custom-report-v1
harness:
system_prompt: Produce a concise operational report
max_llm_calls: 8
mcp_servers:
- protocol: streamable-http
endpoint: https://mcp.example.com/mcp
api_key:
responses:
'201':
description: Success; repeated identical idempotent requests also return 201
content:
application/json:
schema:
$ref: '#/components/schemas/Cronjob'
example:
name: daily-report
prompt: Summarize recent activity
schedule:
cron: 0 9 * * *
at: null
timezone: Asia/Shanghai
enabled: true
timeout_seconds: 1800
misfire_policy: latest
misfire_grace_seconds: 120
harness: null
cronjob_id: 0e58ff7f7dcbf348c252fc70e7fdb587
revision: 1
created_at: '2026-09-16T00:00:00Z'
updated_at: '2026-09-16T00:00:00Z'
next_run_at: '2026-09-16T01:00:00Z'
active: null
last_run: null
'401':
description: >-
Missing or invalid service credentials required by the deployment
gateway; the response format is gateway-defined
'422':
description: Invalid request parameters, schedule, or idempotency key
content:
application/json:
schema:
$ref: '#/components/schemas/CronjobRequestError'
examples:
field:
value:
detail:
- loc:
- path
- job_id
msg: String should match pattern
type: string_pattern_mismatch
value:
value:
detail: Idempotency key already belongs to a different request
security:
- HarnessServiceAuth: []
x-codeSamples:
- lang: cURL
source: |-
curl --request POST "${HARNESS_URL}/harness/cronjobs" \
--header "Authorization: Bearer ${HARNESS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{"name": "daily-report", "prompt": "Summarize recent activity", "schedule": {"cron": "0 9 * * *", "timezone": "Asia/Shanghai"}, "idempotency_key": "daily-report-v1"}'
- lang: Python
source: >-
import json
import os
from urllib.request import Request, urlopen
base_url = os.environ["HARNESS_URL"]
headers = {"Authorization": "Bearer " + os.environ["HARNESS_TOKEN"]}
headers["Content-Type"] = "application/json"
data = json.dumps({'name': 'daily-report', 'prompt': 'Summarize
recent activity', 'schedule': {'cron': '0 9 * * *', 'timezone':
'Asia/Shanghai'}, 'idempotency_key': 'daily-report-v1'}).encode()
request = Request(base_url + f"/harness/cronjobs", headers=headers,
method="POST", data=data)
with urlopen(request) as response:
print(json.load(response))
- lang: JavaScript
source: >-
const baseUrl = process.env.HARNESS_URL;
const headers = { Authorization: `Bearer
${process.env.HARNESS_TOKEN}` };
headers["Content-Type"] = "application/json";
const response = await fetch(`${baseUrl}/harness/cronjobs`, {
method: "POST",
headers,
body: JSON.stringify({"name": "daily-report", "prompt": "Summarize recent activity", "schedule": {"cron": "0 9 * * *", "timezone": "Asia/Shanghai"}, "idempotency_key": "daily-report-v1"}),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
components:
schemas:
CronjobCreateRequest:
properties:
name:
type: string
maxLength: 128
minLength: 1
title: Name
description: Task name, 1–128 characters
prompt:
type: string
maxLength: 65536
minLength: 1
title: Prompt
description: Message sent to the agent on each execution, 1–65536 characters
schedule:
$ref: '#/components/schemas/CronjobSchedule'
description: Trigger schedule
harness:
anyOf:
- $ref: '#/components/schemas/CronjobHarnessOverrides'
- type: 'null'
description: >-
Task-specific overrides using the AgentKit CLI deployment format,
such as mcp_servers
enabled:
type: boolean
title: Enabled
default: true
description: Whether future scheduling is enabled
timeout_seconds:
type: integer
maximum: 10800
minimum: 1
title: Timeout Seconds
default: 1800
description: >-
Execution timeout in seconds; timeout records a failed execution
without automatically retrying it
misfire_policy:
type: string
enum:
- latest
- skip
title: Misfire Policy
default: latest
description: >-
latest runs the most recent missed occurrence; skip runs it only
within the grace period. Neither policy replays every missed
occurrence
misfire_grace_seconds:
type: integer
maximum: 86400
minimum: 0
title: Misfire Grace Seconds
default: 120
description: Maximum lateness in seconds allowed by the skip policy
idempotency_key:
anyOf:
- type: string
maxLength: 128
minLength: 1
- type: 'null'
title: Idempotency Key
description: >-
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
additionalProperties: false
type: object
required:
- name
- prompt
- schedule
title: CreateJob
description: Request to create a task; undeclared fields are rejected
Cronjob:
type: object
properties:
name:
type: string
maxLength: 128
minLength: 1
title: Name
description: Task name, 1–128 characters
prompt:
type: string
maxLength: 65536
minLength: 1
title: Prompt
description: Message sent to the agent on each execution, 1–65536 characters
schedule:
$ref: '#/components/schemas/CronjobSchedule'
description: Trigger schedule
harness:
anyOf:
- $ref: '#/components/schemas/CronjobHarnessPublicOverrides'
- type: 'null'
enabled:
type: boolean
title: Enabled
description: Whether future scheduling is enabled
timeout_seconds:
type: integer
maximum: 10800
minimum: 1
title: Timeout Seconds
description: >-
Execution timeout in seconds; timeout records a failed execution
without automatically retrying it
misfire_policy:
type: string
enum:
- latest
- skip
title: Misfire Policy
description: >-
latest runs the most recent missed occurrence; skip runs it only
within the grace period. Neither policy replays every missed
occurrence
misfire_grace_seconds:
type: integer
maximum: 86400
minimum: 0
title: Misfire Grace Seconds
description: Maximum lateness in seconds allowed by the skip policy
cronjob_id:
type: string
description: Owning task ID
pattern: ^[a-f0-9]{32}$
revision:
type: integer
description: Task revision number
created_at:
type: string
description: Task creation time in UTC
format: date-time
updated_at:
type: string
description: Most recent task update time in UTC
format: date-time
next_run_at:
anyOf:
- type: string
description: >-
Next scheduled occurrence in UTC; null when no future occurrence
remains
format: date-time
- type: 'null'
active:
anyOf:
- $ref: '#/components/schemas/CronjobRun'
- type: 'null'
description: >-
The queued or running execution, or an execution whose final result
is still being persisted
last_run:
anyOf:
- $ref: '#/components/schemas/CronjobRunSummary'
- type: 'null'
description: Summary of the most recently persisted historical execution
required:
- name
- prompt
- schedule
- harness
- enabled
- timeout_seconds
- misfire_policy
- misfire_grace_seconds
- cronjob_id
- revision
- created_at
- updated_at
- next_run_at
- active
- last_run
CronjobRequestError:
type: object
properties:
detail:
anyOf:
- type: string
- type: array
items:
$ref: '#/components/schemas/CronjobValidationError'
description: Business validation message or a list of field validation errors
required:
- detail
CronjobSchedule:
properties:
cron:
anyOf:
- type: string
- type: 'null'
title: Cron
description: >-
Five-field cron expression: minute, hour, day, month, and weekday;
it must have an occurrence within the next eight years
at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: At
description: >-
ISO 8601 timestamp including a timezone offset; must be in the
future when creating an enabled task, mutually exclusive with cron
timezone:
type: string
title: Timezone
default: Asia/Shanghai
description: >-
IANA timezone used for cron; at uses its own offset, but this field
must still be a valid timezone
additionalProperties: false
type: object
title: Schedule
description: >-
A recurring or one-time schedule; exactly one of cron and at must be
non-null
oneOf:
- required:
- cron
properties:
cron:
type: string
at:
type: 'null'
- required:
- at
properties:
at:
type: string
format: date-time
cron:
type: 'null'
CronjobHarnessOverrides:
properties:
model_name:
type: string
title: Model Name
default: ''
description: Reasoning model name used by this task
tools:
type: string
title: Tools
default: ''
description: >-
Comma-separated built-in tool names. See [Built-in
tools](/productions/api-reference/preview/en/harness-runtime/tools)
for all 13 names, their uses, and prerequisites in the default CLI
0.54.0 deployment
mcp_servers:
items:
$ref: '#/components/schemas/CronjobMcpServer'
type: array
title: Mcp Servers
description: Remote MCP service list; a JSON-encoded list string is also accepted
skills:
type: string
title: Skills
default: ''
description: >-
Comma-separated SkillHub slugs, skill space IDs, or space:skill
references
system_prompt:
type: string
title: System Prompt
default: ''
description: Agent instructions for task execution
runtime:
type: string
enum:
- adk
- codex
title: Runtime
default: adk
description: Agent execution backend
registry_space_id:
type: string
title: Registry Space Id
default: ''
description: A2A agent registry space ID
registry_endpoint:
type: string
title: Registry Endpoint
default: ''
description: A2A agent registry endpoint
registry_region:
type: string
title: Registry Region
default: ''
description: A2A agent registry region
registry_top_k:
type: integer
minimum: 1
title: Registry Top K
default: 3
description: Number of candidate agents to retrieve, at least 1
max_llm_calls:
anyOf:
- type: integer
minimum: 1
- type: 'null'
title: Max Llm Calls
description: Maximum model calls per execution, at least 1
additionalProperties: false
type: object
title: JobHarnessOverrides
description: >-
Settings applied to each execution of this task; explicit fields
override the deployed agent and omitted fields inherit it
CronjobHarnessPublicOverrides:
properties:
model_name:
type: string
title: Model Name
description: Reasoning model name used by this task
tools:
type: string
title: Tools
description: >-
Comma-separated built-in tool names. See [Built-in
tools](/productions/api-reference/preview/en/harness-runtime/tools)
for all 13 names, their uses, and prerequisites in the default CLI
0.54.0 deployment
mcp_servers:
type: array
items:
$ref: '#/components/schemas/CronjobMcpServerPublic'
description: MCP services used by the task with credentials masked
skills:
type: string
title: Skills
description: >-
Comma-separated SkillHub slugs, skill space IDs, or space:skill
references
system_prompt:
type: string
title: System Prompt
description: Agent instructions for task execution
runtime:
type: string
enum:
- adk
- codex
title: Runtime
description: Agent execution backend
registry_space_id:
type: string
title: Registry Space Id
description: A2A agent registry space ID
registry_endpoint:
type: string
title: Registry Endpoint
description: A2A agent registry endpoint
registry_region:
type: string
title: Registry Region
description: A2A agent registry region
registry_top_k:
type: integer
minimum: 1
title: Registry Top K
description: Number of candidate agents to retrieve, at least 1
max_llm_calls:
anyOf:
- type: integer
minimum: 1
- type: 'null'
title: Max Llm Calls
description: Maximum model calls per execution, at least 1
additionalProperties: false
type: object
title: CronjobHarnessPublicOverrides
description: >-
Settings applied to each execution of this task; explicit fields
override the deployed agent and omitted fields inherit it
CronjobRun:
type: object
properties:
cronjob_id:
type: string
description: Owning task ID
pattern: ^[a-f0-9]{32}$
run_id:
type: string
description: Execution ID used to read or cancel this occurrence
pattern: ^[0-9]{13}-[a-f0-9]{20}$
revision:
type: integer
description: Task revision used for this execution
scheduled_at:
type: string
description: Scheduled occurrence time in UTC
format: date-time
created_at:
type: string
description: Execution record creation time in UTC
format: date-time
prompt:
type: string
description: Prompt for this execution
harness:
anyOf:
- $ref: '#/components/schemas/CronjobHarnessPublicOverrides'
- type: 'null'
timeout_seconds:
type: integer
description: Timeout in seconds for this execution
state:
type: string
description: Execution state
enum:
- queued
- running
- succeeded
- failed
- cancelled
- skipped
- interrupted
owner:
anyOf:
- type: string
description: >-
Identifier of the replica executing this occurrence; null before
execution begins
- type: 'null'
started_at:
anyOf:
- type: string
description: Execution start time in UTC; null before execution begins
format: date-time
- type: 'null'
completed_at:
anyOf:
- type: string
description: Execution completion time in UTC; null while unfinished
format: date-time
- type: 'null'
lease_until:
anyOf:
- type: string
description: >-
Current execution lease expiry in UTC; null before execution
begins
format: date-time
- type: 'null'
cancel_requested:
type: boolean
description: Whether cancellation has been requested for this execution
output:
type: string
description: >-
Execution output; empty on failure. Successful output is limited to
1 MiB
error:
type: string
description: >-
Failure, cancellation, skip, or interruption details; empty when
there is no error
coalesced_from:
type: string
description: >-
Earliest missed occurrence combined into this run, in UTC; present
only when occurrences were coalesced
format: date-time
required:
- cronjob_id
- run_id
- revision
- scheduled_at
- created_at
- prompt
- harness
- timeout_seconds
- state
- owner
- started_at
- completed_at
- lease_until
- cancel_requested
- output
- error
CronjobRunSummary:
type: object
properties:
run_id:
type: string
description: Execution ID used to read or cancel this occurrence
pattern: ^[0-9]{13}-[a-f0-9]{20}$
state:
type: string
description: Execution state
enum:
- succeeded
- failed
- cancelled
- skipped
- interrupted
scheduled_at:
type: string
description: Scheduled occurrence time in UTC
format: date-time
completed_at:
anyOf:
- type: string
description: Execution completion time in UTC; null while unfinished
format: date-time
- type: 'null'
error:
type: string
description: >-
Failure, cancellation, skip, or interruption details; empty when
there is no error
required:
- run_id
- state
- scheduled_at
- completed_at
- error
CronjobValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
description: Location of the invalid field
msg:
type: string
title: Message
description: Validation message
type:
type: string
title: Error Type
description: Validation error code
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
CronjobMcpServer:
properties:
protocol:
type: string
enum:
- streamable-http
- sse
title: Protocol
default: streamable-http
description: MCP transport protocol
endpoint:
type: string
title: Endpoint
description: >-
HTTP(S) URL without username, password, fragment, or control
characters
api_key:
anyOf:
- type: string
format: password
writeOnly: true
- type: 'null'
title: Api Key
description: >-
MCP service credential as a single-line string; persisted with the
task and masked in read responses
additionalProperties: false
type: object
required:
- endpoint
title: McpServerConfig
description: A remote MCP service available to this task
CronjobMcpServerPublic:
properties:
protocol:
type: string
enum:
- streamable-http
- sse
title: Protocol
description: MCP transport protocol
endpoint:
type: string
title: Endpoint
description: >-
HTTP(S) URL without username, password, fragment, or control
characters
api_key:
anyOf:
- type: string
- type: 'null'
description: >-
A configured non-empty credential is returned as ********; omitted
credentials may be absent or null
additionalProperties: false
type: object
required:
- endpoint
title: CronjobMcpServerPublic
description: A remote MCP service available to this task
securitySchemes:
RuntimeBearer:
type: http
scheme: bearer
description: >-
Optional locally without a gateway; cloud deployments use the Runtime
API key or user-pool JWT required by that deployment, never the model
API key
HarnessServiceAuth:
type: http
scheme: bearer
description: >-
Runtime access credential for a service-authenticated Harness, such as a
Runtime API key; shared OAuth deployments do not support background
scheduled tasks
````