The schedule management endpoints let you inspect, trigger, and refresh @schedule directives registered by the exec runtime. Use these to audit active cron jobs, review historical fires, reload registrations after script changes, and trigger an immediate fire for testing or recovery.

List Schedules

GET /api/v1/exec/schedules/list

Returns every currently registered @schedule directive, with the computed next fire time and the most recent fire outcome for each.

This endpoint takes no parameters.

cURL

curl -X GET "https://api.example.com/api/v1/exec/schedules/list" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.exec.schedules.listSchedules();

Response

200

{
  "total": 1,
  "schedules": [
    {
      "scriptPath": "/srv/scripts/default/cron/cleanup.ts",
      "scriptRel": "default/cron/cleanup.ts",
      "subdomain": "default",
      "execId": "default",
      "vmCacheKey": "default:default/cron/cleanup.ts",
      "expression": "0 * * * *",
      "timeoutMs": 30000,
      "registeredAt": "2026-01-01T00:00:00.000Z",
      "nextFire": "2026-01-15T13:00:00.000Z",
      "lastFireAt": "2026-01-15T12:00:00.000Z",
      "lastFireStatus": "ok",
      "lastFireRunId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}

400

{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T12:00:00.000Z"
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid input	Request parameters failed validation	Check parameter format and requirements

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2026-01-15T12:00:00.000Z"
}

503

{
  "error": "Service unavailable",
  "code": "ERROR_503",
  "timestamp": "2026-01-15T12:00:00.000Z"
}

Schedule History

GET /api/v1/exec/schedules/history

Returns newest-first NDJSON entries from the fires log. Use the query parameters to narrow the window to a specific script or a time range, and to opt into scanning rotated log files.

Parameters

Name	In	Type	Required	Description
scriptPath	query	string	No	Filter entries to a specific script (relative to scripts-dir).
since	query	string	No	ISO 8601 lower bound on ts.
limit	query	integer	No	Max entries to return. Default 100, hard max 1000.
includeRotated	query	boolean	No	When true, also scan rotated fires.log.* files (slower). Default false.

cURL

curl -X GET "https://api.example.com/api/v1/exec/schedules/history?scriptPath=default/cron/cleanup.ts&limit=50" \
  -H "Authorization: Bearer <token>"

SDK

const history = await client.exec.schedules.scheduleHistory({
  scriptPath: "default/cron/cleanup.ts",
  since: "2026-01-15T00:00:00Z",
  limit: 50,
  includeRotated: false,
});

Response

200

{
  "total": 2,
  "limit": 50,
  "includeRotated": false,
  "entries": [
    {
      "ts": "2026-01-15T12:00:00.000Z",
      "scriptPath": "default/cron/cleanup.ts",
      "expression": "0 * * * *",
      "runId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "ok",
      "durationMs": 142,
      "returnPreview": "{\"deleted\":12}"
    },
    {
      "ts": "2026-01-15T11:00:00.000Z",
      "scriptPath": "default/cron/cleanup.ts",
      "expression": "0 * * * *",
      "runId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "status": "error",
      "durationMs": 87,
      "error": "TypeError: cannot read property 'id' of undefined"
    }
  ]
}

400

{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T12:00:00.000Z"
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid input	Request parameters failed validation	Check parameter format and requirements

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2026-01-15T12:00:00.000Z"
}

503

{
  "error": "Service unavailable",
  "code": "ERROR_503",
  "timestamp": "2026-01-15T12:00:00.000Z"
}

Reload Schedules

POST /api/v1/exec/schedules/reload

Rescans the scripts directory and reconciles the registered schedules against the current filesystem contents. Pass dry_run: true to preview the diff (added, kept, removed) without applying it.

This endpoint takes no query, path, or header parameters.

Request Body

Name	Type	Required	Default	Description
dry_run	boolean	No	false	When true, compute the diff against the filesystem but do not apply. Returns the same shape with added, kept, removed lists.

cURL

curl -X POST "https://api.example.com/api/v1/exec/schedules/reload" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'

SDK

const result = await client.exec.schedules.reloadSchedules({
  dry_run: true,
});

Response

200

{
  "dry_run": true,
  "added": ["default/cron/new-job.ts"],
  "kept": ["default/cron/cleanup.ts"],
  "removed": ["default/cron/deprecated.ts"],
  "failed": [
    {
      "path": "default/cron/broken.ts",
      "reason": "Invalid cron expression: 'every blue moon'"
    }
  ]
}

400

{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T12:00:00.000Z"
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid input	Request parameters failed validation	Check parameter format and requirements

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2026-01-15T12:00:00.000Z"
}

503

{
  "error": "Service unavailable",
  "code": "ERROR_503",
  "timestamp": "2026-01-15T12:00:00.000Z"
}

Note

The failed array is populated in both dry_run and apply responses, so you can surface registration problems (bad cron expression, @websocket combined with @schedule, preflight compile errors) before committing a reload.

Trigger Schedule

POST /api/v1/exec/schedules/trigger

Manually fires a registered schedule once. Useful for replaying a missed fire or testing a cron expression outside its natural cadence.

This endpoint takes no query, path, or header parameters.

Request Body

Name	Type	Required	Default	Description
scriptPath	string	Yes	—	Script path (absolute or relative to scripts-dir) of a script with a valid @schedule directive.
force	boolean	No	false	When true, bypass the @token refusal. Use with care — this fires the script as cron (no token auth).

cURL

curl -X POST "https://api.example.com/api/v1/exec/schedules/trigger" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"scriptPath": "default/cron/cleanup.ts", "force": false}'

SDK

const result = await client.exec.schedules.triggerSchedule({
  scriptPath: "default/cron/cleanup.ts",
  force: false,
});

Response

200

{
  "triggered": true,
  "scriptPath": "default/cron/cleanup.ts",
  "runId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "status": "ok",
  "durationMs": 198
}

400

{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T12:00:00.000Z"
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid input	Request parameters failed validation	Check parameter format and requirements

403

{
  "error": "Access denied",
  "code": "FORBIDDEN",
  "timestamp": "2026-01-15T12:00:00.000Z"
}

Error Code	Title	Description	Resolution
FORBIDDEN	Access denied	Insufficient permissions for this operation	Contact administrator for access

404

{
  "error": "Resource not found",
  "code": "NOT_FOUND",
  "timestamp": "2026-01-15T12:00:00.000Z"
}

Error Code	Title	Description	Resolution
NOT_FOUND	Resource not found	The requested resource does not exist	Verify the resource identifier

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2026-01-15T12:00:00.000Z"
}

503

{
  "error": "Service unavailable",
  "code": "ERROR_503",
  "timestamp": "2026-01-15T12:00:00.000Z"
}

Caution

Set force: true only when you intentionally want to bypass the @token check. A triggered fire runs with the same privileges as the cron worker, so the response will succeed even if the script would normally refuse a request without a valid token.