Skip to main content

​
Cron API

Create, list, and delete cron jobs directly on the OpenClaw gateway. Cron jobs run recurring tasks on your agent using the gateway’s built-in scheduler.
These endpoints manage cron jobs on the gateway itself via POST /tools/invoke. For application-level scheduled tasks stored in the database, see the scheduled tasks API.
Cron is enabled by default on all new instances. The provisioning template sets a maximum of 2 concurrent runs and 24-hour session retention. You can adjust these limits using the config API.
All cron endpoints require session authentication.

​
List cron jobs

GET /api/cron
Returns all cron jobs from the gateway, including disabled jobs.

​
Response

{
  "jobs": [
    {
      "id": "heartbeat",
      "name": "Heartbeat",
      "enabled": true,
      "schedule": {
        "kind": "every",
        "everyMs": 1800000
      },
      "payload": {
        "kind": "systemEvent",
        "text": "Heartbeat check — review emails, calendar, and recent activity."
      },
      "lastRun": "2026-03-30T01:00:00Z",
      "nextRun": "2026-03-30T01:30:00Z"
    }
  ],
  "total": 1,
  "source": "gateway"
}

​
Job object

FieldTypeDescription
idstringJob identifier
namestringJob display name
enabledbooleanWhether the job is active
scheduleobjectSchedule configuration. Contains kind (every for interval-based) and timing fields like everyMs (interval in milliseconds) or expr (cron expression).
payloadobjectJob payload sent to the agent when the job runs
lastRunstring | nullISO 8601 timestamp of the last execution
nextRunstring | nullISO 8601 timestamp of the next scheduled execution

​
Response fields

FieldTypeDescription
jobsarrayList of cron job objects
totalnumberTotal number of jobs
sourcestringData source — gateway on success, gateway-error when the gateway is unreachable

​
Gateway errors

When the gateway is unreachable, the endpoint returns HTTP 200 with an empty job list and the error detail: 
{
  "jobs": [],
  "error": "Gateway unreachable",
  "source": "gateway-error"
}

​
Example

curl -X GET https://agentbot.raveculture.xyz/api/cron \
  -H "Cookie: next-auth.session-token=YOUR_SESSION"

​
Create a cron job

POST /api/cron
Adds a new cron job to the gateway.

​
Request body

FieldTypeRequiredDescription
namestringYesJob name
scheduleobjectYesSchedule configuration. Use { "kind": "every", "everyMs": 3600000 } for interval-based schedules, or { "kind": "cron", "expr": "0 9 * * *" } for cron expressions.
payloadobjectYesJob payload sent to the agent on each run
enabledbooleanNoWhether the job starts active. Defaults to true.

​
Example request

{
  "name": "Daily digest",
  "schedule": {
    "kind": "every",
    "everyMs": 86400000
  },
  "payload": {
    "kind": "systemEvent",
    "text": "Generate a daily activity digest."
  }
}

​
Response

{
  "success": true,
  "source": "gateway"
}

​
Errors

CodeDescription
400name, schedule, and payload required — one or more required fields are missing
401Unauthorized — no valid session
502Gateway error — the gateway rejected the request or is unreachable

​
Example

curl -X POST https://agentbot.raveculture.xyz/api/cron \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION" \
  -d '{
    "name": "Daily digest",
    "schedule": { "kind": "every", "everyMs": 86400000 },
    "payload": { "kind": "systemEvent", "text": "Generate a daily activity digest." }
  }'

​
Delete a cron job

DELETE /api/cron?jobId=heartbeat
Removes a cron job from the gateway.

​
Query parameters

ParameterTypeRequiredDescription
jobIdstringYesID of the job to delete

​
Response

{
  "success": true,
  "source": "gateway"
}

​
Errors

CodeDescription
400jobId required — the jobId query parameter is missing
401Unauthorized — no valid session
502Gateway error — the gateway rejected the request or is unreachable

​
Example

curl -X DELETE "https://agentbot.raveculture.xyz/api/cron?jobId=heartbeat" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION"