Sokko Docs
Platform API

Schedules

Make an agent run a task on a cron schedule: create, list and delete schedules.

A schedule makes an agent run a prompt at fixed times: every morning at 7:00, every Monday, the first day of the month. The agent runs the task on its own, with its skills, MCP servers, connected apps and memory. No end user and no conversation is involved.

The platform does not deliver the result of a scheduled run to you. A run sends no webhook and writes to no conversation. Write the prompt so that the task itself delivers its result through a tool: an MCP server of yours, or a connected app (send the email, post the message, write the row).

All paths on this page start with:

https://sokko.ai/api/v1/workspaces/{workspaceId}/agents/{agentId}

The examples use $BASE for that prefix. The agent must be ready for every call on this page: schedules live in the running agent.

Create a schedule

POST /schedules
FieldTypeRules
namestringRequired. 1 to 80 characters, not starting with [. Unique among the agent's schedules.
cronstringRequired. A five-field cron expression. See below.
promptstringRequired. 1 to 4,000 characters. What the agent does at each run.
timezonestringOptional. An IANA time zone name such as Europe/Brussels.
curl $BASE/schedules \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Morning order summary",
    "cron": "0 7 * * 2-7",
    "prompt": "Read the orders for today with the orders tool. Send the summary to the shop owner with the send_summary tool.",
    "timezone": "Europe/Brussels"
  }'

The answer is 201:

{
  "id": "4f8a2c1e9b7d",
  "name": "Morning order summary",
  "cron": "0 7 * * 2-7",
  "prompt": "Read the orders for today with the orders tool. Send the summary to the shop owner with the send_summary tool.",
  "timezone": "Europe/Brussels",
  "enabled": true,
  "managedBy": null,
  "nextRunAt": "2026-11-21T06:00:00.000Z",
  "lastRunAt": null,
  "lastStatus": null
}

The name is the key of a schedule. A second schedule with the name of an existing one answers 409 schedule_exists, whatever its other fields are, so a create you send again after a lost answer cannot make the task run twice. The name is compared as written, after the spaces at its ends are removed.

A schedule cannot be changed. Delete it and create it again.

The id of a schedule is a short string, not a UUID. Treat it as opaque.

Five-field cron

cron has exactly five fields, separated by spaces:

┌───────── minute        0 to 59
│ ┌─────── hour          0 to 23
│ │ ┌───── day of month  1 to 31
│ │ │ ┌─── month         1 to 12
│ │ │ │ ┌─ day of week   0 to 7 (0 and 7 are Sunday)
│ │ │ │ │
0 7 * * 2-7

Each field takes numbers, *, lists with ,, ranges with - and steps with /. Names such as MON or JAN, a seconds field, and shortcuts such as @daily are refused.

ExpressionRuns
0 7 * * *Every day at 7:00.
*/15 * * * *Every 15 minutes.
30 8 * * 1-5Monday to Friday at 8:30.
0 9 1 * *The first day of each month at 9:00.
0 8,18 * * *Every day at 8:00 and at 18:00.

Send timezone when the hour matters. Without it the agent's own time zone applies, and the schedule object shows "timezone": null. If the create answers 400 with a message about timezone, that agent runs every schedule in its own time zone: send the schedule without the field.

Each run calls a model, which costs credits of the workspace. A schedule that runs every few minutes adds up.

Errors

StatusCodeWhen
400invalid_requestA bad name, a cron expression that is not five fields or has a value out of range, an unknown time zone.
404not_foundNo such agent in this workspace.
409agent_not_readyThe agent is not ready.
409agent_busyThe agent is being upgraded to a newer recipe version. Try again when the upgrade has ended.
409schedule_existsThe agent has a schedule with this name.
503agent_unavailableThe agent's scheduler did not answer. List the schedules before you try again: the schedule can exist.

List schedules

GET /schedules
curl $BASE/schedules \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY"
{
  "data": [
    {
      "id": "4f8a2c1e9b7d",
      "name": "Morning order summary",
      "cron": "0 7 * * 2-7",
      "prompt": "Read the orders for today with the orders tool. Send the summary to the shop owner with the send_summary tool.",
      "timezone": "Europe/Brussels",
      "enabled": true,
      "managedBy": null,
      "nextRunAt": "2026-11-22T06:00:00.000Z",
      "lastRunAt": "2026-11-21T06:00:03.812Z",
      "lastStatus": "ok"
    }
  ],
  "nextCursor": null
}

The answer holds every schedule of the agent in one page. nextCursor is always null.

FieldMeaning
cronThe expression. null for a task the agent set for itself with a schedule that is not a cron expression.
enabledfalse for a paused schedule.
managedByrecipe for a schedule that the agent's recipe created, else null. An upgrade replaces the recipe's schedules and leaves yours.
nextRunAtWhen the next run is due, or null.
lastRunAtThe time of the last run, or null before the first run.
lastStatusok or error for the last run, null before the first run.

The list also shows schedules the agent created itself, for example when an operator asked it in a conversation to "remind me every Friday".

The time and the status of the last run are all the API reports about a run. The output of the run is not available.

Errors: 404 not_found, 409 agent_not_ready, 503 agent_unavailable.

Delete a schedule

DELETE /schedules/{scheduleId}
curl -X DELETE $BASE/schedules/4f8a2c1e9b7d \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY"
{ "id": "4f8a2c1e9b7d", "deleted": true }

A delete is permanent. If you delete a schedule that a recipe created, the next upgrade of the agent creates it again.

Errors: 404 not_found (no such agent or schedule), 409 agent_not_ready, 409 agent_busy (the agent is being upgraded), 503 agent_unavailable.

On this page