CreatePolarClawCronJob

Creates a PolarClaw scheduled task.

Operation description

Request

Use this API to create a cron job. You can configure the job's payload, execution frequency, timezone, target channel, recipients, and a failure alert mechanism.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

No authorization for this operation. If you encounter issues with this operation, contact technical support.

Request syntax

POST  HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
ApplicationId	string	Yes	The application ID.	pa-**************
Name	string	Yes	The unique name of the task.	daily-report
Schedule	object	Yes	The schedule configuration.	{"Kind":"cron","Expr":"0 9 * * *","Tz":"Asia/Shanghai"}
Kind	string	No	The type of schedule.	cron
Expr	string	No	The cron expression that specifies when the task runs.	0 9 * * *
Tz	string	No	The time zone for the schedule.	Asia/Shanghai
StaggerMs	integer	No	The deterministic jitter window, in milliseconds.	0
EveryMs	integer	No	The task execution interval, in milliseconds.	100000
AnchorMs	integer	No	The anchor timestamp for aligning interval-based schedules, in milliseconds.	1777370572518
At	string	No	The specific time for a one-time execution, specified as an ISO 8601 timestamp.	2026-04-10T09:00:00+08:00
SessionTarget	string	Yes	The session target. Valid values are `main`, `isolated`, and `current`.	main
WakeMode	string	Yes	The wake mode for the agent. Valid values are `now` and `next-heartbeat`.	now
Payload	object	Yes	The execution payload configuration.	{"Kind":"agentTurn","Message":"Generate the daily report."}
Kind	string	No	The payload type. Valid values are `agentTurn` and `systemEvent`.	systemEvent
Message	string	No	The prompt for an agent conversation, used when `Kind` is `agentTurn`.	Generate the daily report.
Text	string	No	The text for the system event, used when `Kind` is `systemEvent`.	Generate the daily report.
Model	string	No	Specifies a model that overrides the agent's default model.	bailian/qwen3.5-plus
Fallbacks	array	No	A list of fallback models to use if the primary model fails.
	string	No	A fallback model.	bailian/qwen-max
Thinking	string	No	The thinking level for the agent's response generation. Valid values are `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`.	xhigh
TimeoutSeconds	integer	No	The execution timeout, in seconds.	10
LightContext	boolean	No	Specifies whether to use a light context for the agent conversation.	false
Deliver	boolean	No	Specifies whether to deliver the agent's output to a channel.	true
Channel	string	No	The ID of the delivery channel.	feishu
To	string	No	The specific target or recipient within the channel.	ou_***
BestEffortDeliver	boolean	No	Specifies whether to use best-effort delivery. If `true`, delivery failures are ignored.	false
AgentId	string	No	The ID of the agent that executes the task.	main
SessionKey	string	No	The session routing key, which determines the conversation session for the task.	agent:main:feishu:direct:***
Description	string	No	A description of the task.	Daily report generation
Enabled	boolean	No	Specifies whether the cron job is enabled. Default: `true`.	true
DeleteAfterRun	boolean	No	Specifies whether to automatically delete the job after its first execution. This is useful for one-time tasks. Default: `false`.	false
Delivery	object	No	The configuration for delivering task execution results.	{"Mode":"announce","Channel":"telegram"}
Mode	string	No	The delivery mode. Valid values are `none`, `announce`, and `webhook`.	announce
Channel	string	No	The delivery channel.	feishu
AccountId	string	No	The account ID for the delivery channel.	default
To	string	No	The recipient for the delivery.	ou_***
BestEffort	boolean	No	Specifies whether to use best-effort delivery. If `true`, delivery failures are ignored.	false
FailureAlert	object	No	The failure alert configuration.	{"After":3,"Channel":"telegram"}
After	integer	No	The number of consecutive failures required to trigger an alert.	3
Channel	string	No	The channel for sending failure alerts.	feishu
AccountId	string	No	The account ID for the alert channel.	default
To	string	No	The recipient for the failure alert.	ou_***
CooldownMs	integer	No	The cooldown period, in milliseconds, between alerts for the same job.	5000
Mode	string	No	The mode for sending alerts. Valid values are `announce` and `webhook`.	announce
RunImmediately	boolean	No	Specifies whether to run the job once immediately upon creation. Default: `false`.	false
Restart	boolean	No	Specifies whether to restart the gateway upon job creation. Default: `true`.	true

Response elements

Element	Type	Description	Example
	object	Response schema.
RequestId	string	The request ID.	6BD9CDE4-5E7B-4BF3-9BB8-83C73E******
Message	string	The response message.	successful
Code	integer	The response status code.	200
ApplicationId	string	The application ID.	pa-**************
Ok	boolean	Indicates whether the operation was successful.	true
Job	object	Details of the created cron job.
Id	string	The job ID (UUID).	e2c57423-12f0-45cc-a387-6155168b3201
Name	string	The job name.	test
Enabled	boolean	Indicates whether the cron job is enabled.	true
DeleteAfterRun	boolean	Indicates whether the cron job is deleted after its first run.	false
CreatedAtMs	integer	The creation timestamp in milliseconds.	1777368967284
UpdatedAtMs	integer	The update timestamp in milliseconds.	1777370572517
Schedule	object	The schedule configuration.
Kind	string	The schedule type. Valid values: `cron`, `every`, and `at`.	cron
Expr	string	The cron expression.	0 9 * * *
Tz	string	The IANA time zone.	Asia/Shanghai
EveryMs	integer	The interval in milliseconds.	1000
AnchorMs	integer	The anchor timestamp for interval alignment.	1777370572518
At	string	The ISO 8601 timestamp.	2026-04-10T09:00:00+08:00
SessionTarget	string	The session target. Valid values: `main`, `isolated`, and `current`.	main
WakeMode	string	The wake mode. Valid values: `now` and `next-heartbeat`.	now
Payload	object	The execution payload.
Kind	string	The payload type. Valid values: `agentTurn` and `systemEvent`.	agentTurn
Message	string	The agent prompt.	Generate the daily report.
Text	string	The system event text.	Generate the daily report.
Model	string	The overriding model.	bailian/qwen3.5-plus
TimeoutSeconds	integer	The execution timeout in seconds.	10
LightContext	boolean	Indicates whether to use a light context.	false
Deliver	boolean	Indicates whether to deliver the output to the delivery channel.	false
Channel	string	The delivery channel ID.	feishu
To	string	The recipient.	ou_***
BestEffortDeliver	boolean	Specifies whether to ignore delivery failures.	false
AgentId	string	The ID of the executing agent.	main
SessionKey	string	The session key.	agent:main:feishu:direct:***
Description	string	The job description.	test
Delivery	object	The delivery configuration.
Mode	string	The delivery mode. Valid values: `none`, `announce`, and `webhook`.	announce
Channel	string	The delivery channel.	feishu
AccountId	string	The channel account ID.	default
To	string	The recipient.	ou_***
BestEffort	boolean	Specifies whether to ignore delivery failures.	false
State	object	The current state of the job.
NextRunAtMs	integer	The next run timestamp in milliseconds.	1777424400000
LastRunAtMs	integer	The last run timestamp in milliseconds.	1777370544931
LastRunStatus	string	The last run status.	ok
ConsecutiveErrors	integer	The number of consecutive execution failures.	0
Runs	array<object>	The run history.
	array<object>
Ts	integer	The run timestamp in milliseconds.	1777370572518
JobId	string	The associated job ID.	f83f5278-1abe-40a6-b10e-ad3ecdc05de2
Action	string	The action performed. Valid values: `finished`, `error`, and `skipped`.	finished
Status	string	The status of the run. Valid values: `ok`, `error`, and `skipped`.	ok
Summary	string	The run summary.	Generate the daily report.
Delivered	boolean	Specifies whether the results were delivered.	false
DeliveryStatus	string	The delivery status.	not-requested
SessionId	string	The associated session ID.	***
RunAtMs	integer	The actual execution timestamp in milliseconds.	1777370544931
DurationMs	integer	The execution duration in milliseconds.	27586
NextRunAtMs	integer	The next run timestamp in milliseconds.	1777424400000
Model	string	The model used for the run.	bailian/qwen3.5-plus
Provider	string	The model provider.	bailian
Usage	object	The token usage details.
InputTokens	integer	The number of input tokens.	30250
OutputTokens	integer	The number of output tokens.	30250
TotalTokens	integer	The total number of tokens.	60500
JobName	string	The job name.	test
RanImmediately	boolean	Indicates whether the job ran immediately after creation.	false

Examples

Success response

JSON format

{
  "RequestId": "6BD9CDE4-5E7B-4BF3-9BB8-83C73E******",
  "Message": "successful",
  "Code": 200,
  "ApplicationId": "pa-**************",
  "Ok": true,
  "Job": {
    "Id": "e2c57423-12f0-45cc-a387-6155168b3201",
    "Name": "test",
    "Enabled": true,
    "DeleteAfterRun": false,
    "CreatedAtMs": 1777368967284,
    "UpdatedAtMs": 1777370572517,
    "Schedule": {
      "Kind": "cron",
      "Expr": "0 9 * * *",
      "Tz": "Asia/Shanghai",
      "EveryMs": 1000,
      "AnchorMs": 1777370572518,
      "At": "2026-04-10T09:00:00+08:00"
    },
    "SessionTarget": "main",
    "WakeMode": "now",
    "Payload": {
      "Kind": "agentTurn",
      "Message": "Generate the daily report.",
      "Text": "Generate the daily report.",
      "Model": "bailian/qwen3.5-plus",
      "TimeoutSeconds": 10,
      "LightContext": false,
      "Deliver": false,
      "Channel": "feishu",
      "To": "ou_***",
      "BestEffortDeliver": false
    },
    "AgentId": "main",
    "SessionKey": "agent:main:feishu:direct:***",
    "Description": "test",
    "Delivery": {
      "Mode": "announce",
      "Channel": "feishu",
      "AccountId": "default",
      "To": "ou_***",
      "BestEffort": false
    },
    "State": {
      "NextRunAtMs": 1777424400000,
      "LastRunAtMs": 1777370544931,
      "LastRunStatus": "ok",
      "ConsecutiveErrors": 0
    },
    "Runs": [
      {
        "Ts": 1777370572518,
        "JobId": "f83f5278-1abe-40a6-b10e-ad3ecdc05de2",
        "Action": "finished",
        "Status": "ok",
        "Summary": "Generate the daily report.",
        "Delivered": false,
        "DeliveryStatus": "not-requested",
        "SessionId": "***",
        "RunAtMs": 1777370544931,
        "DurationMs": 27586,
        "NextRunAtMs": 1777424400000,
        "Model": "bailian/qwen3.5-plus",
        "Provider": "bailian",
        "Usage": {
          "InputTokens": 30250,
          "OutputTokens": 30250,
          "TotalTokens": 60500
        },
        "JobName": "test"
      }
    ]
  },
  "RanImmediately": false
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.