# Schedule Management

**Page:** api/exec/scheduling

[Download Raw Markdown](./api/exec/scheduling.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



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.




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




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







```json
{
  "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"
    }
  ]
}
```




```json
{
  "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 |




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




```json
{
  "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`. |




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




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







```json
{
  "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"
    }
  ]
}
```




```json
{
  "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 |




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




```json
{
  "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. |




```bash
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}'
```




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







```json
{
  "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'"
    }
  ]
}
```




```json
{
  "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 |




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




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








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). |




```bash
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}'
```




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







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




```json
{
  "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 |




```json
{
  "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 |




```json
{
  "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 |




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




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








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.