You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 02c9024
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: content/(dynamic)/crons.mdx
+41-7Lines changed: 41 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -23,7 +23,7 @@ A response under 400 is a success and is silent. A response of 400 or worse, or
23
23
24
24
## Declare it
25
25
26
-
There is no write API and no dashboard editor. `sf.jsonc` is the only writer, and a publish is the only edit. That is what makes a rollback restore the previous schedules for free.
26
+
There is no write API and no dashboard editor. `sf.jsonc` is the only writer, and a publish is the only edit. That is what makes a rollback restore the previous schedules for free, placed against your current allowance.
27
27
28
28
```jsonc sf.jsonc
29
29
{
@@ -43,13 +43,13 @@ Validation is blocking. A bad cron fails the publish rather than shipping a sche
43
43
44
44
## Schedule syntax
45
45
46
-
Three grammars. Pick whichever reads best.
46
+
Three grammars in two kinds. Named and shorthand schedules are **simple** crons. Five-field crontab schedules are **advanced** crons, and your plan sets how many of each a Space runs.
47
47
48
48
| Kind | Examples | Notes |
49
49
| --- | --- | --- |
50
-
| Named |`hourly`, `daily`, `twicedaily`, `weekly`| The provider picks the moment |
51
-
| Shorthand |`3h`, `2d`, `1w`|Hours up to 12, days up to 23, weeks up to 6. `N` is at least 1|
52
-
| Crontab |`30 16 * * 1-5`, `*/15 * * * *`| Five fields, down to every minute |
50
+
| Named (simple) |`hourly`, `daily`, `twicedaily`, `weekly`| The provider picks the moment |
51
+
| Shorthand (simple) |`3h`, `2d`, `1w`|`N` runs per hour, day, or week: `3h` runs three times an hour. Up to 12 an hour, 23 a day, 6 a week|
52
+
| Crontab (advanced) |`30 16 * * 1-5`, `*/15 * * * *`| Five numeric fields, down to every minute |
53
53
54
54
Crontab fields are minute `0-59`, hour `0-23`, day of month `1-31`, month `1-12`, weekday `0-7`. Lists (`1,15`), ranges (`1-5`), `*`, and a `/step` over a span are supported.
55
55
@@ -69,7 +69,32 @@ Your schedule string is stored verbatim and never normalized.
69
69
70
70
Each entry gets a **key** derived by slugging its path. `/api/cron/digest` becomes `api-cron-digest`. Two paths that slug to the same key are rejected at publish.
71
71
72
-
A Space can declare at most **8** crons.
72
+
## Allowance by plan
73
+
74
+
Each Space runs a set number of simple and advanced crons, by plan:
75
+
76
+
| Plan | Simple | Advanced | With Boost |
77
+
| --- | --- | --- | --- |
78
+
| Free | 1 | 0 | No Boost. Upgrade the plan |
79
+
| Go | 5 | 0 | 25 simple, 5 advanced |
80
+
| Plus | 10 | 5 | 30 simple, 5 advanced |
81
+
| Enterprise | 50 | 25 | No Boost |
82
+
83
+
Boost is a per-Space add-on on Go and Plus. It adds 20 simple crons and raises advanced crons to at least 5, so on Plus it adds simple crons only. Free has no Boost: upgrading the plan is the way to more crons.
84
+
85
+
Each cron takes a slot of its own kind, in the order you declare them. A later crontab can still take an advanced slot after an earlier simple cron ran out of simple slots:
86
+
87
+
- A crontab takes an advanced slot while one is left.
88
+
- A crontab with no advanced slot left still publishes, with a warning. It runs at its closest simple schedule and counts against the simple allowance. That can run more or less often than the crontab asked, and not at the times it names: `*/5 * * * *` runs `12h` (12 times an hour), and `0 9 * * 1-5` runs `5w` (5 times a week, not necessarily on weekdays at 9:00).
89
+
- Crons past the allowance still publish, and the publish carries a warning. Within each kind of slot, the first ones declared run. The rest show as not scheduled, "over this plan's cron limit", on the dashboard's **Crons** page and in `sf crons ls`.
90
+
91
+
Advanced crons also run at their closest simple schedule for now, until advanced scheduling is enabled for the platform.
92
+
93
+
A raised limit applies right away. After an upgrade or Boost, crons that were waiting start running without a publish.
94
+
95
+
A lowered limit applies at your next publish, promote or rollback. Until then, a downgrade or Boost ending changes nothing: crons that are running keep running.
96
+
97
+
For now, whatever the plan, a Space can declare at most **8** crons, and past that the publish fails validation. Each tier is capped at 8 too, so `allowance` in the API reports the capped numbers (8 simple and 5 advanced on Plus, 8 and 8 on Gold and Enterprise), and Boost adds no crons on a plan already at the cap. The ceiling rises to the plan limits above as the runtime update reaches every box.
73
98
74
99
## List and trigger
75
100
@@ -105,4 +130,13 @@ Only the newest failures are kept, with no history behind them. A real failure a
105
130
106
131
## API
107
132
108
-
[`listSpaceCrons`](/api/reference/spaces/listspacecrons) is `GET /v1/spaces/{spaceId}/crons`. It returns the version the schedules came from, which is `null` before the first publish. Each entry carries its key, path, schedule, and recent failures.
133
+
[`listSpaceCrons`](/api/reference/spaces/listspacecrons) is `GET /v1/spaces/{spaceId}/crons`. It returns the version the schedules came from, which is `null` before the first publish. Each entry carries its key, path, schedule, and recent failures, plus:
134
+
135
+
| Field | Meaning |
136
+
| --- | --- |
137
+
|`scheduled`| Whether the cron runs |
138
+
|`tier`|`simple` or `advanced`. `null` when not scheduled |
139
+
|`runsAs`| The schedule that actually runs. `null` when not scheduled |
140
+
|`reason`|`over_plan_limit` past the allowance, `unsupported_schedule` for a schedule that cannot run. `null` when scheduled |
141
+
142
+
The response's `allowance` carries the Space's `simple` and `advanced` counts and `upgrade`, the step that unlocks more: `upgrade_plan`, `upgrade_or_boost`, `boost`, or `null` when there is none.
Copy file name to clipboardExpand all lines: content/(reference)/config-file.mdx
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -202,7 +202,7 @@ See [Functions](/functions).
202
202
203
203
| Key | Type | Default | What it does |
204
204
| --- | --- | --- | --- |
205
-
|`crons`| array, up to 8 entries | none | Scheduled requests |
205
+
|`crons`| array, up to 8 entries for now | none | Scheduled requests. Your plan sets how many run, see [Crons](/crons#allowance-by-plan)|
206
206
|`crons[].path`| string, up to 512 chars | none | Path to GET. Starts with `/`, no query, no wildcards, no `:placeholders`|
207
207
|`crons[].schedule`| string | none | A named schedule, a shorthand, or a five-field crontab |
208
208
@@ -236,15 +236,15 @@ See [Redirects, rewrites, and headers](/routing).
236
236
| --- | --- |
237
237
| File size | 256 KiB |
238
238
|`templates` entries | 100 |
239
-
|`crons` entries | 8 |
239
+
|`crons` entries | 8 for now |
240
240
|`crons[].path`| 512 characters |
241
241
|`name`| 255 characters |
242
242
|`meta.title`| 300 characters |
243
243
|`meta.description`| 1000 characters |
244
244
|`meta.image`, `meta.favicon`| 2000 characters |
245
245
|`superpowers.javascriptTags` entries | 16, each `code` up to 8 KiB |
246
246
247
-
A plan may lower these caps. None of them can be raised.
247
+
A plan may lower these caps. None of them can be raised. The `crons` cap is the same on every plan: your plan sets how many of the declared crons run, see [Crons](/crons#allowance-by-plan).
| Templates in `sf.jsonc`| 100 |`config_templates_over_limit`|
44
-
| Cron jobs per space | 8 | Config validation error |
44
+
| Cron jobs declared per space | 8 for now, until the runtime update reaches every box. Your plan sets how many run, see [Crons](/crons#allowance-by-plan)| Config validation error |
45
45
| Data sources in `sf.jsonc`| 32 | Config validation error |
0 commit comments