RUN JOB

Description

Trigger a run for a specified Job.

Note that the SQL statement does not end with ;

Syntax

RUN JOB `<job_name>`

Example

Example command for trigger a Job run.

RUN JOB `count_transactions`

Example request for a Job that allows concurrent runs, where the Idempotency-Key header identifies the submission.

curl --location 'https://api.onehouse.ai/v1/resource/' \
--header 'x-onehouse-account-uid: <ACCOUNT_UID>' \
--header 'x-onehouse-project-uid: <PROJECT_UID>' \
--header 'x-onehouse-api-key: <API_KEY>' \
--header 'x-onehouse-api-secret: <API_SECRET>' \
--header 'x-onehouse-link-uid: <PROJECT_REQUEST_ID>' \
--header 'x-onehouse-region: <PROJECT_REGION>' \
--header 'x-onehouse-uuid: <USER_ID>' \
--header 'Idempotency-Key: count_transactions-2026-08-19' \
--header 'Content-Type: application/json' \
--data '{
    "statement": "RUN JOB `count_transactions`"
}'

Required parameters

• <job_name>: Name of the Job to run.
  • The Job must already be created.

Headers

Send the required headers for every SQL Command API request, plus the following.

Name	When	Description
Idempotency-Key	Required for Jobs with MAX_CONCURRENT_RUNS greater than 1. Recommended for all Jobs.	Client-generated key identifying this submission, kept stable across retries of it. If a run of the Job already exists with the same key, Onehouse returns that run's jobRunId instead of starting a second run.

Notes on Idempotency-Key:

• The header name is case-insensitive — Idempotency-Key and idempotency-key are the same header.
• Concurrent Jobs need it because the limit above 1 removes the "one run at a time" guard that otherwise stopped a duplicate submission. It is the key, not the limit, that makes a retry safe.
• Use one key per logical run — for example the Airflow run_id of the task attempt, or a date-partitioned key such as count_transactions-2026-08-19. Do not reuse a key across Jobs.
• Sending the same key with different per-run argument overrides is rejected with Idempotency key <key> was already used with different arguments.
• If you omit the header, Onehouse generates a key for that one request. The submission is still accepted, but a retry of it is treated as a new run rather than a repeat, which is exactly the duplicate the key exists to prevent.

Per-run argument overrides

A run may override the Job's arguments for that run only. The override is layered over the Job's PARAMETERS: it can change the value of an argument or add a new one, and an argument it does not name is inherited unchanged. There is no syntax for removing one.

Arguments only

Overrides apply to the Job's arguments — the values your application code reads. They cannot change Spark properties (--conf) or Hudi configurations (--hudi-conf): those are part of the Job configuration and are applied from the Job definition on every run. To change a Spark or Hudi property, use ALTER JOB to update the Job's PARAMETERS.

Concurrency

A run is admitted only if the Job has fewer active (Queued or Running) runs than its MAX_CONCURRENT_RUNS, which defaults to 1. When the Job is already at its limit, the command fails and the Status API reports Spark Job <job_id> already has <N> active run(s) (max <N>). Raise the limit with ALTER JOB, and see Concurrent Job runs for the requirements.

Status API

Status API response

• API_OPERATION_STATUS_SUCCESS from Status API confirms that the Job has been submitted, but does not reflect its execution status. To monitor the Job's status, send a request to the DESCRIBE JOB_RUN API, and refer to sparkJobRun.status field from its Status API response.
• API_OPERATION_STATUS_FAILED from Status API does not necessarily mean the Job was not submitted. To confirm whether the Job was submitted, send a request to the DESCRIBE JOB API, and refer to sparkJobRun.latestJobStatus and sparkJobRun.latestJobRunSubmittedAt fields from its Status API response.

Example Status API response

The Status API response of a successful Job submission.

{
    "apiStatus": "API_OPERATION_STATUS_SUCCESS",
    "apiResponse": {
        "runJobApiResponse": {
            "jobRunId": "<job_run_id>"
        }
    }
}