Cron jobs

Every /v1 route for cron jobs. This page is generated from the API's OpenAPI contract, so it always matches what the API accepts and returns.

Authentication, pagination, errors and idempotency work the same on every route. They are described once, in the API overview.

Get a cron run

GET /v1/cron-runs/{runId}

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`runId`	`string`	yes	The run's id.

Returns

200 with V1CronRun.

bash

curl "https://api.naijacloud.com/v1/cron-runs/$RUN_ID" \
  -H "Authorization: Bearer $NC_API_KEY"

A cron run's output, oldest line first

GET /v1/cron-runs/{runId}/logs

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`runId`	`string`	yes	The run's id.

Query parameters

Name	Type	Required	Notes
`limit`	`integer`	no	Rows per page. Ignored when a cursor is given.
`cursor`	`string`	no	The `nextCursor` of the previous page, unchanged.

Returns

200 with a page: { data: V1CronRunLogLine[], nextCursor }, where each item is V1CronRunLogLine.

bash

curl "https://api.naijacloud.com/v1/cron-runs/$RUN_ID/logs" \
  -H "Authorization: Bearer $NC_API_KEY"

Change a cron job's schedule or command

PATCH /v1/services/{serviceId}/cron

Takes effect from the next scheduled run.

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service's id.

Body

Field	Type	Required	Notes
`schedule`	`string`	no	Five-field cron expression, in UTC. e.g. `0 3 * * *`
`command`	`string`	no	The command each run executes.

Returns

200 with V1CronSettings.

bash

curl -X PATCH "https://api.naijacloud.com/v1/services/$SERVICE_ID/cron" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schedule":"0 3 * * *"}'

List a cron job's runs, newest first

GET /v1/services/{serviceId}/runs

Key scopes: READ and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service's id.

Query parameters

Name	Type	Required	Notes
`limit`	`integer`	no	Rows per page. Ignored when a cursor is given.
`cursor`	`string`	no	The `nextCursor` of the previous page, unchanged.

Returns

200 with a page: { data: V1CronRun[], nextCursor }, where each item is V1CronRun.

bash

curl "https://api.naijacloud.com/v1/services/$SERVICE_ID/runs" \
  -H "Authorization: Bearer $NC_API_KEY"

Run a cron job now

POST /v1/services/{serviceId}/runs

Needs a built image: deploy the job first.

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service's id.

Headers

Name	Type	Required	Notes
`Idempotency-Key`	`string`	no	Any unique string (1–255 printable characters). A retry with the same key and body returns the first response instead of acting twice, for 24 hours.

Returns

202 with V1CronRun.

bash

curl -X POST "https://api.naijacloud.com/v1/services/$SERVICE_ID/runs" \
  -H "Authorization: Bearer $NC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Resume scheduled runs

POST /v1/services/{serviceId}/cron/resume

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service's id.

Returns

204 with no body.

bash

curl -X POST "https://api.naijacloud.com/v1/services/$SERVICE_ID/cron/resume" \
  -H "Authorization: Bearer $NC_API_KEY"

Pause scheduled runs

POST /v1/services/{serviceId}/cron/suspend

Manual runs still work while paused.

Key scopes: WRITE and PLATFORM_API.

Path parameters

Name	Type	Required	Notes
`serviceId`	`string`	yes	The service's id.

Returns

204 with no body.

bash

curl -X POST "https://api.naijacloud.com/v1/services/$SERVICE_ID/cron/suspend" \
  -H "Authorization: Bearer $NC_API_KEY"

Types

V1CronRun

Field	Type	Notes
`id`	`string (uuid)`
`serviceId`	`string (uuid)`
`seq`	`number`, or `null`	Run number for this job, from 1.
`status`	`QUEUED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `TIMED_OUT`, `SKIPPED`
`trigger`	`SCHEDULED`, `MANUAL`
`exitCode`	`number`, or `null`
`error`	`string`, or `null`
`commitSha`	`string`, or `null`
`createdAt`	`string (date-time)`
`startedAt`	`string (date-time)`, or `null`
`finishedAt`	`string (date-time)`, or `null`

V1CronRunLogLine

Field	Type	Notes
`id`	`string (uuid)`
`line`	`string`
`stream`	`OUTPUT`, `SYSTEM`
`createdAt`	`string (date-time)`

V1CronSettings

Field	Type	Notes
`serviceId`	`string (uuid)`
`schedule`	`string`, or `null`	e.g. `0 3 * * *`
`command`	`string`, or `null`
`suspended`	`boolean`	Scheduled runs are paused.