← Back to blog

Importing 300 checks from a spreadsheet — all of them or none

2026-11-16

guideheartbeat

Most teams already have their list of things to monitor somewhere. It's a spreadsheet of cron jobs, an inventory of endpoints, or a list of certificates. Typing 300 of them into a form takes an afternoon. The import, under Checks → Import from CSV/JSON or POST /v1/checks/import, does it in one request.

This post is mostly about what happens when the file is wrong. A 300-row file almost always is wrong somewhere.

The rule: one bad row, zero checks

Importing is all-or-nothing. If any row is invalid, or the batch would take you over your plan's check limit, nothing is written. You get the same row-by-row report back. A partial import would leave you comparing your file with the dashboard to work out which rows made it in.

All the inserts run in one database transaction. It takes the same per-organisation lock as creating a single check, and it counts your active checks again inside that lock. If a teammate adds a check between your preview and your import and that puts you over the limit, the import is refused. It is never half-applied.

A minimal file

type,name,url,interval_seconds,grace_seconds,cron_expression,cron_timezone
http,API health,https://api.example.com/health,300,,,
heartbeat,Queue worker,,600,120,,
cron,Nightly backup,,,900,0 3 * * 1-5,Europe/Paris

These are the accepted CSV columns, in any order: type, name, url, method, interval_seconds, timeout_seconds, grace_seconds, failure_threshold, enabled, cron_expression, cron_timezone. Header names are not case-sensitive, and the byte-order mark some spreadsheet exports put at the start of the file is removed. type is http when empty. The other types are heartbeat, cron, tls and domain. An empty cell gets the same default as in the API: a 300-second interval, a 10-second timeout, a failure threshold of 2, and enabled.

The cron row keeps its schedule. cron_expression and cron_timezone work in CSV as well as in JSON, because a list of cron jobs is the main reason to import in bulk. With a schedule, the deadline is the next scheduled run plus the grace period, in the timezone you named. If you leave the timezone out, UTC is used. The cron job that stopped running explains why a weekday-only job needs this, and the cron expression tester shows what an expression will actually do. Imported heartbeat and cron checks are created by the same code as checks made in the form, so each one gets its own ping URL.

CSV can't express assertions. A header named assertions rejects the file with assertions can't be expressed in CSV — use the JSON format for those. The JSON format is an array of objects with the same fields as POST /v1/checks, assertions included.

Preview first

The request body looks like this:

{"format": "csv", "data": "<the file contents>", "dry_run": true}

You set format explicitly to "csv" or "json". The server doesn't guess it. dry_run: true runs everything except the write. The preview and the real import use the same endpoint and the same code, so the preview can't promise something the import then refuses. For the file above, on a new Free organisation, the preview returns:

{"rows":[
  {"line":2,"name":"API health","type":"http","target":"https://api.example.com/health","valid":true},
  {"line":3,"name":"Queue worker","type":"heartbeat","valid":true},
  {"line":4,"name":"Nightly backup","type":"cron","valid":true}],
 "summary":{"total":3,"valid":3,"invalid":0,"created":0,
            "active_now":0,"limit":5,"over_limit_by":0}}

Send the same body without dry_run and you get a 201 with "created":3.

In the dashboard, the Import button only appears after a preview. Editing the file clears the preview, and the button sends exactly the payload you previewed. The API doesn't make you preview. A request without dry_run imports straight away, and it is still all-or-nothing.

A rejected file

type,name,url,interval_seconds,grace_seconds,cron_expression,cron_timezone
http,API health,https://api.example.com/health,300,,,
heartbeat,Queue worker,,10m,120,,
cron,Nightly backup,,,900,0 3 * * 1-5,Europe/Pari
http,Status page,api.example.com/status,300,,,

The preview's rows, shortened:

{"line":2,"name":"API health","valid":true}
{"line":3,"name":"Queue worker","valid":false,"error":"interval_seconds: \"10m\" is not a whole number"}
{"line":4,"name":"Nightly backup","valid":false,"error":"unknown timezone: \"Europe/Pari\""}
{"line":5,"name":"Status page","valid":false,"error":"url must be a valid http(s) URL"}

The summary says "total":4,"valid":1,"invalid":3. If you import anyway, you get a 422 with the same body, and no checks are created. That includes line 2, even though it was valid.

Every row is validated exactly like a single POST /v1/checks, using the same function. That covers your plan's minimum interval, the 24-hour maximum, a 1–60 s timeout, a failure threshold of 1–10 and a grace period of 0–86,400 s. A cron expression must have a next run date, and the shortest gap between its runs can't be below your plan's minimum interval.

Line numbers count the header as line 1, so the first data row is line 2. There are two caveats. Blank lines are skipped and not counted, so after a blank line the numbers are one lower than your editor shows. In JSON, line is the object's position in the array, starting at 1, not a line in the file.

A typo fails the whole file

The worst import mistake is the one that succeeds. Write interval instead of interval_seconds and a lenient parser drops the column it doesn't know. It then creates 300 checks on the default 300-second interval, and everything looks fine.

So an unknown column rejects the file before any row is read:

422 {"message":"unknown column \"interval\" in the header row"}

The same typo as a JSON key gets could not read JSON: json: unknown field "interval". These errors are about the whole file, so they come without a row-by-row report.

Going over the plan limit

Take eight HTTP rows on a new Free organisation, where the limit is five active checks. All eight rows are valid, and the preview says so:

"summary":{"total":8,"valid":8,"invalid":0,"created":0,
           "active_now":0,"limit":5,"over_limit_by":3}

The dashboard tells you: "This would put you 3 over your plan's limit of 5 active checks (you have 0). Upgrade or set enabled to false on some rows — paused checks don't count." If you import anyway, you get a 403 and nothing is written. The import does not quietly create the first five rows.

Only enabled rows count toward the limit, as everywhere else in okokumo. Set enabled to false on three of the eight rows and the same import returns 201 with "created":8: five running, three paused. The limits are 5 active checks on Free, 20 on Starter, 100 on Pro and 500 on Business (pricing). Importing 300 active checks therefore needs Business.

The other limits

  • At most 500 rows per import (at most 500 checks per import, got …).
  • The file contents must be under 1 MB (413, import must be under 1024 KB).
  • You can authenticate with a dashboard session or an API key. Requests count toward the same per-organisation /v1 rate limit as the rest of the API.
  • Owners, admins and members can all import, the same people who can create checks one at a time (who can do what).

New to okokumo? Create your first check by hand to see what each field does, then import the rest.

Try the free tool: Cron expression tester