Job Executor -- Execution API

The Execution API controls the lifecycle of job executions. It provides endpoints to start, stop, pause, resume, and restart executions, as well as query execution details and history.

Base URL: http://localhost:9000

Execution control endpoints use the /api/v2/job prefix. Execution query endpoints use the /jobExecution prefix.

Execution Control Endpoints

Method	Path	Description
POST	/api/v2/job/start	Start a job execution
POST	/api/v2/job/stop	Stop a running execution
POST	/api/v2/job/pause	Pause a running execution
POST	/api/v2/job/resume	Resume a paused execution
POST	/api/v2/job/restart	Restart execution from a specific step

Execution Query Endpoints

Method	Path	Description	Authority
GET	/jobExecution/\{id\}	Get execution by ID	JobExecutor:JobExecution:read
GET	/jobExecution/last/\{jobId\}	Get last execution for a job	JobExecutor:JobExecution:read
POST	/jobExecution/job/\{jobId\}	Search execution history	JobExecutor:JobExecution:read
GET	/jobExecution/jobs/\{jobId\}/execution-summary	Get execution metrics	JobExecutor:JobExecution:read

---

POST /api/v2/job/start

Start execution of a job. Creates a Temporal workflow that runs the job's steps sequentially.

Request body (JobExecutionStartRequest):

{
  "jobId": "job-abc-123",
  "parameters": {
    "reportMonth": "2026-03",
    "recipients": "finance@example.com"
  },
  "async": true,
  "triggeredBy": "api",
  "triggerSource": "mcp-server"
}

Field	Type	Required	Description
jobId	string	Yes	The ID of the job to execute.
parameters	object	No	Key-value input parameters passed to the automation steps.
async	boolean	No	If true (default), returns immediately. If false, waits for completion.
triggeredBy	string	No	How the execution was triggered (e.g., api, schedule, webhook, manual).
triggerSource	string	No	Source identifier (e.g., mcp-server, ui, cron).

Response:

{
  "executionId": "exec-xyz-789",
  "jobId": "job-abc-123",
  "status": "RUNNING",
  "workflowId": "wf-temporal-001",
  "startedAt": "2026-04-02T10:00:00Z"
}

---

POST /api/v2/job/stop

Stop a running execution. The current step is terminated and no further steps execute. This action is irreversible.

Request body (JobExecutionPauseStopRequest):

{
  "jobExecutionId": "exec-xyz-789",
  "reason": "Incorrect parameters, will re-run."
}

Field	Type	Required	Description
jobExecutionId	string	Yes	The execution ID to stop.
reason	string	No	Reason for stopping. Logged in execution history.

Response (JobActionResponse):

{
  "executionId": "exec-xyz-789",
  "action": "STOP",
  "status": "STOPPED",
  "message": "Execution stopped successfully.",
  "timestamp": "2026-04-02T10:01:00Z"
}

---

POST /api/v2/job/pause

Pause a running execution. The currently executing step will finish, but no further steps will start until the execution is resumed.

Request body (JobExecutionPauseStopRequest):

{
  "jobExecutionId": "exec-xyz-789",
  "reason": "Awaiting manual approval."
}

Response:

{
  "executionId": "exec-xyz-789",
  "action": "PAUSE",
  "status": "PAUSED",
  "message": "Execution paused successfully.",
  "timestamp": "2026-04-02T10:00:08Z"
}

---

POST /api/v2/job/resume

Resume a previously paused execution. The next pending step begins executing.

Request body (JobExecutionResumeRequest):

{
  "jobExecutionId": "exec-xyz-789"
}

Response:

{
  "executionId": "exec-xyz-789",
  "action": "RESUME",
  "status": "RUNNING",
  "message": "Execution resumed successfully.",
  "timestamp": "2026-04-02T10:05:00Z"
}

---

POST /api/v2/job/restart

Restart a failed or stopped execution from a specific step. All steps before the restart point are skipped, and their previous results are retained.

Request body (JobExecutionResumeRequest):

{
  "jobExecutionId": "exec-xyz-789",
  "fromStepId": "step-002"
}

Field	Type	Required	Description
jobExecutionId	string	Yes	The execution ID to restart.
fromStepId	string	No	The step ID to restart from. If omitted, restarts from the failed step.

Response:

{
  "executionId": "exec-xyz-789",
  "action": "RESTART",
  "status": "RUNNING",
  "message": "Execution restarted from step 'Generate PDF Report'.",
  "timestamp": "2026-04-02T10:10:00Z"
}

---

GET /api/v2/job/job-resume

Resume a paused execution with an approval decision. Used for human-in-the-loop approval workflows.

Query parameters:

Parameter	Type	Required	Description
jobExecutionId	string	Yes	The execution ID.
approve	boolean	Yes	true to approve and continue, false to reject and stop.

Example:

curl "http://localhost:9000/api/v2/job/job-resume?jobExecutionId=exec-xyz-789&approve=true"

---

GET /jobExecution/{id}

Get the full details of a specific execution, including all step executions.

Example:

curl http://localhost:9000/jobExecution/exec-xyz-789

Response:

{
  "status": "Success",
  "message": "JobExecution fetched successfully",
  "data": {
    "id": "exec-xyz-789",
    "jobId": "job-abc-123",
    "jobName": "Send Monthly Sales Report",
    "status": "COMPLETED",
    "startTime": "2026-04-02T10:00:00Z",
    "endTime": "2026-04-02T10:00:12Z",
    "durationMs": 12400,
    "triggeredBy": "api",
    "triggerSource": "mcp-server",
    "parameters": {
      "reportMonth": "2026-03"
    },
    "stepExecutions": [
      {
        "id": "step-exec-001",
        "stepId": "step-001",
        "stepName": "Query Sales Data",
        "status": "COMPLETED",
        "startTime": "2026-04-02T10:00:01Z",
        "endTime": "2026-04-02T10:00:05Z",
        "durationMs": 4000,
        "output": { "rowCount": 1547 }
      },
      {
        "id": "step-exec-002",
        "stepId": "step-002",
        "stepName": "Generate PDF Report",
        "status": "COMPLETED",
        "startTime": "2026-04-02T10:00:06Z",
        "endTime": "2026-04-02T10:00:10Z",
        "durationMs": 4000,
        "output": { "fileName": "sales-report-2026-03.pdf" }
      },
      {
        "id": "step-exec-003",
        "stepId": "step-003",
        "stepName": "Send Email",
        "status": "COMPLETED",
        "startTime": "2026-04-02T10:00:10Z",
        "endTime": "2026-04-02T10:00:12Z",
        "durationMs": 2000,
        "output": { "recipients": ["finance@example.com"] }
      }
    ]
  }
}

---

GET /jobExecution/last/{jobId}

Get the most recent execution for a given job.

Example:

curl http://localhost:9000/jobExecution/last/job-abc-123

Returns the same structure as GET /jobExecution/\{id\}.

---

POST /jobExecution/job/{jobId}

Search execution history for a specific job with pagination and sorting.

Request body (JobExecutionSearchRequest):

{
  "page": 0,
  "size": 20,
  "sortField": "startTime",
  "sortDirection": "desc"
}

Field	Type	Default	Description
page	integer	0	Page number (zero-based).
size	integer	10	Page size.
sortField	string	startTime	Field to sort by.
sortDirection	string	desc	Sort direction (asc or desc).

Response:

{
  "status": "Success",
  "message": "JobExecutions fetched",
  "data": [
    {
      "id": "exec-xyz-789",
      "status": "COMPLETED",
      "startTime": "2026-04-02T10:00:00Z",
      "endTime": "2026-04-02T10:00:12Z",
      "durationMs": 12400,
      "triggeredBy": "api"
    },
    {
      "id": "exec-xyz-788",
      "status": "COMPLETED",
      "startTime": "2026-03-28T14:30:00Z",
      "endTime": "2026-03-28T14:30:11Z",
      "durationMs": 11200,
      "triggeredBy": "schedule"
    }
  ]
}

---

GET /jobExecution/jobs/{jobId}/execution-summary

Get aggregated execution metrics for a job.

Example:

curl http://localhost:9000/jobExecution/jobs/job-abc-123/execution-summary

Response:

{
  "status": "Success",
  "message": "Job execution summary fetched",
  "data": {
    "totalExecutions": 48,
    "successCount": 46,
    "failureCount": 2,
    "successRate": 95.8,
    "avgDurationMs": 12400,
    "minDurationMs": 8200,
    "maxDurationMs": 25600,
    "lastExecutedAt": "2026-04-02T10:00:00Z",
    "lastStatus": "COMPLETED"
  }
}