Tasks and schedules

Golden represents background work as runs and recurring configuration as definitions. Both are available through /api/jobs; the former /api/tasks routes are not the current API. Task administration requires ADMIN.

Task status

SUCCEEDED, FAILED, CANCELLED, and SKIPPED are terminal. A successful run can still report records skipped or refused by a load. Read its message and output and verify the intended data outcome.

Inspect task instances

Set the connection values as in the API quickstart, using an administrator token. Set RUN_ID to the identifier returned by the operation you started.

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $GOLDEN_TOKEN" \
  "$GOLDEN_URL/api/jobs/runs?status=RUNNING&page=0&size=20"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $GOLDEN_TOKEN" \
  "$GOLDEN_URL/api/jobs/runs/$RUN_ID"

The list uses a content array. A single-run response is the run itself, without a task wrapper. It includes id, jobType, status, message, timestamps, and optional failure information. progress, when present, is on a 0–1 scale; it is not the old 0–100 completion field. Treat progress as contextual information rather than a guarantee of remaining time.

GET /api/jobs/runs/{id}/chain reads related runs. A retry can produce another run: preserve identifiers instead of following a name alone.

Follow a quality measurement

POST /api/quality/measurements returns run.id. Follow that run to a terminal state, then read the saved observation through the quality metrics API. A successful quality-measurement run reports WRITTEN and the measurement time in its output. A table with quality disabled fails without writing a picture. The task measures one entity’s table and does not recalculate its records.

Request cancellation

curl --fail-with-body --silent --show-error -X POST \
  -H "Authorization: Bearer $GOLDEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Source correction required"}' \
  "$GOLDEN_URL/api/jobs/runs/$RUN_ID/cancel"

An accepted request returns 202. Continue reading the run until terminal. An already-terminal run conflicts; an unknown identifier is not found. Cancellation does not undo committed work. Inspect the resulting records or deliveries before deciding to repeat the original operation.

Inspect schedules

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $GOLDEN_TOKEN" \
  "$GOLDEN_URL/api/jobs/definitions?page=0&size=20"

A definition has an id, jobType, enabled state, scheduleKind, and scheduling parameters. Supported kinds are CRON, INTERVAL, ONCE, and MANUAL. Cron schedules carry cronExpression and timeZone; do not assume a host’s local timezone or a five-field Unix cron expression.

Use GET /api/jobs/definitions/{id}/next-runs?count=10 to preview execution times. Read nextRunAt, inertReason, and the definition’s enabled state rather than assuming a saved expression is currently firing.

Golden creates definitions through product configuration. Direct POST /api/jobs/definitions is denied, including for administrators. Configure source/entity schedules through their owning product controls.

Change or run a schedule

Read a definition with response headers before changing it:

curl --fail-with-body --silent --show-error \
  -D definition-headers.txt \
  -H "Authorization: Bearer $GOLDEN_TOKEN" \
  "$GOLDEN_URL/api/jobs/definitions/$DEFINITION_ID"

Use its returned ETag unchanged as the If-Match header. For example, if the response contains ETag: "3", disabling future starts uses:

curl --fail-with-body --silent --show-error -X PUT \
  -H "Authorization: Bearer $GOLDEN_TOKEN" \
  -H 'If-Match: "3"' \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}' \
  "$GOLDEN_URL/api/jobs/definitions/$DEFINITION_ID/enabled"

The version is an example, not a constant. If it changed, reread the definition and reconcile your change. Disabling scheduling does not cancel an active run.

To run an eligible definition immediately:

curl --fail-with-body --silent --show-error -X POST \
  -H "Authorization: Bearer $GOLDEN_TOKEN" \
  "$GOLDEN_URL/api/jobs/definitions/$DEFINITION_ID/run"

The accepted response identifies the new execution with runId. Poll that run. Review overlapping work before using force: it bypasses the overlap check, not all eligibility checks.

Respond to failure

Read errorType, errorMessage, message, status, and timestamps. Correct the reported configuration or data problem, inspect prior effects, and then choose an appropriate retry or a new product operation. An automatic or requested retry is not a transaction rollback.

See Recover tasks and deliveries and the Tasks API for request and response schemas.