> ## Documentation Index
> Fetch the complete documentation index at: https://developer.opus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute Job

> Run a workflow with populated inputs

This is the primary step where you provide all inputs and run the workflow.

The request body consists of:

* The `jobExecutionId` from the [Initiate Job](/api-reference/jobs/initiate-job) step
* The `jobPayloadSchemaInstance` — the schema from [Get Workflow Details](/api-reference/jobs/get-workflow-details) with values populated for each input
* A `callbackUrl` that Opus will POST to when the job finishes

<Note>
  Job execution is asynchronous. This endpoint returns immediately once the run is queued; the final result is delivered to your `callbackUrl` (and is also retrievable via [Get Job Results](/api-reference/jobs/get-job-results)).
</Note>

## Headers

<ParamField header="x-service-key" type="string" required>
  Your API authentication key
</ParamField>

## Body Parameters

<ParamField body="jobExecutionId" type="string" required>
  The ID of the job to execute (received from Initiate Job)
</ParamField>

<ParamField body="jobPayloadSchemaInstance" type="object" required>
  An object where each key is a variable name from your workflow schema, and each value is a Variable Object (see below).
</ParamField>

<ParamField body="callbackUrl" type="string" required>
  HTTPS URL that Opus will POST the job result to once the run finishes. Must be reachable from the Opus platform.
</ParamField>

<ParamField body="workspaces" type="string">
  Optional comma-separated workspace IDs used to validate workflow access. Used by machine-key callers that operate across multiple workspaces.
</ParamField>

### Variable Object

Each entry in `jobPayloadSchemaInstance` uses your variable name as the key (e.g., `VARIABLE_NAME_1`) and maps to an object with the following properties:

<ParamField body="value" type="any" required>
  The value for this input (type depends on field type)
</ParamField>

<ParamField body="type" type="string" required>
  The data type: str, float, bool, date, file, array, array\_files, or object
</ParamField>

<ParamField body="displayName" type="string">
  The variable name displayed in the Opus platform UI
</ParamField>

<Warning>
  While `displayName` is optional, omitting it may cause display glitches on the Opus platform UI. We strongly recommend including it for each input field.
</Warning>

## Response

<ResponseField name="success" type="boolean" required>
  Whether the job execution was successfully started
</ResponseField>

<ResponseField name="jobExecutionId" type="string" required>
  The job execution ID
</ResponseField>

<ResponseField name="message" type="string" required>
  Status message
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://operator.opus.com/job/execute \
    --header 'Content-Type: application/json' \
    --header 'x-service-key: {YOUR_SERVICE_KEY}' \
    --data '{
      "jobExecutionId": "{YOUR_JOB_EXECUTION_ID}",
      "callbackUrl": "https://your-app.example.com/opus/callback",
      "jobPayloadSchemaInstance": {
        "{VARIABLE_NAME_1}": {
          "value": "API Test Project",
          "type": "str",
          "displayName": "Variable Name 1"
        },
        "{VARIABLE_NAME_2}": {
          "value": 45.8,
          "type": "float",
          "displayName": "Variable Name 2"
        }
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://operator.opus.com/job/execute"
  headers = {
      "Content-Type": "application/json",
      "x-service-key": "{YOUR_SERVICE_KEY}"
  }
  payload = {
      "jobExecutionId": "{YOUR_JOB_EXECUTION_ID}",
      "callbackUrl": "https://your-app.example.com/opus/callback",
      "jobPayloadSchemaInstance": {
          "{VARIABLE_NAME_1}": {
              "value": "API Test Project",
              "type": "str",
              "displayName": "Variable Name 1"
          },
          "{VARIABLE_NAME_2}": {
              "value": 45.8,
              "type": "float",
              "displayName": "Variable Name 2"
          }
      }
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://operator.opus.com/job/execute", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-service-key": "{YOUR_SERVICE_KEY}",
    },
    body: JSON.stringify({
      jobExecutionId: "{YOUR_JOB_EXECUTION_ID}",
      callbackUrl: "https://your-app.example.com/opus/callback",
      jobPayloadSchemaInstance: {
        "{VARIABLE_NAME_1}": {
          value: "API Test Project",
          type: "str",
          displayName: "Variable Name 1",
        },
        "{VARIABLE_NAME_2}": {
          value: 45.8,
          type: "float",
          displayName: "Variable Name 2",
        },
      },
    }),
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Response theme={null}
  {
    "success": true,
    "jobExecutionId": "{JOB_EXECUTION_ID}",
    "message": "Job execution has been started"
  }
  ```
</ResponseExample>