BizKitHub
DocsAPI ReferenceCron Run/api/v1/cron-run/start
postCron RunPublic API v1

/api/v1/cron-run/start

Opens a new run and returns its id. Errors: PUBLIC_CRON_JOB_CODE_INVALID, PUBLIC_CRON_JOB_LIMIT_EXCEEDED, PUBLIC_CRON_RUN_LIMIT_EXCEEDED, PUBLIC_CRON_RUN_RATE_LIMITED, PUBLIC_REQUEST_VALIDATION_FAILED. A meta over 16 KB is stored as a truncation marker. Counts into the cron monitor quota of the API key (10,000 requests per hour, separate from other endpoints). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix seconds).

cron-runpostApiV1Cron-runStart

Parameters

JSON body

Request body

application/json
codestringRequired

Job type identifier. A code seen for the first time creates the job automatically. Normalized to [A-Za-z0-9._:-], max 64 characters. Recommended form: <application>:<job>. Keep it stable: never put ids, dates or arguments into it.

Length: 1–200
Exampleeshop:sync-orders
namestring | nullOptional
One of 2:
Variant 1
string

Human-readable job name shown in the admin. Ignored when empty, equal to code, or after the job was renamed in the admin.

Length: 0–128
Variant 2
null
expirationnumber | nullOptional
One of 2:
Variant 1
number

Idle timeout in seconds. Every log / heartbeat call extends it again. When no call arrives in time the run is closed as timeout and a critical log entry is written. Default 3600 (60 min).

Range: 10–604800
Example900
Variant 2
null
metaobject | nullOptional
One of 2:
Variant 1
object

Context of the run (host, version, arguments), up to 16 KB of JSON.

Variant 2
null
tierstring | nullOptional
One of 2:
Variant 1
string

Scheduler bucket, filterable in the admin job list.

Length: 0–48
Examplenightly
Variant 2
null
idempotencyKeystring | nullOptional
One of 2:
Variant 1
string

When a call is retried with the same key for the same job, the existing run is returned (reused: true).

Length: 0–64
Variant 2
null
schedulestring | nullOptional
One of 2:
Variant 1
string

Expected schedule as a cron expression (5 fields, or 6 with leading seconds; macros like @daily). Enables the dead man's switch: when no run starts within the grace period after an expected time, a critical "missed run" alert is raised. null removes the schedule, omitting it keeps the stored one (falls back to meta.schedule). An invalid value does not reject the run; it is ignored and reported in warnings. A schedule edited in the admin takes precedence.

Length: 0–120
Example*/5 * * * *
Variant 2
null
scheduleTimezonestring | nullOptional
One of 2:
Variant 1
string

IANA time zone of schedule. Default UTC.

Length: 0–64
ExampleEurope/Prague
Variant 2
null
graceSecondsstring | integer | nullOptional
One of 2:
Variant 1
string | integer

Seconds after an expected start before it counts as missed. Default 10 % of the interval, at least 5 min, at most 1 h.

One of 2:
Variant 1
stringinteger
Default: 0
Variant 2
integer

Seconds after an expected start before it counts as missed. Default 10 % of the interval, at least 5 min, at most 1 h.

Range: 0–604800
Variant 2
null

Response schema

1 status code documented

200Success

This response returns no JSON body.

Response example

application/json
{
  "success": true
}

Request example

POST /api/v1/cron-run/start

post
curl -X POST "https://api.bizkithub.com/api/v1/cron-run/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "code": "eshop:sync-orders"
}'

Need an API key?

All BizKitHub public API endpoints require authentication via API key.

Get API Key