Get workflow dispatch job details

Read the current status and file delivery counts of a workflow batch file dispatch job. data.dispatch_job.status reaching completed means batch file delivery processing has finished, not that the triggered per-file workflow jobs have completed; continue with View workflow jobs to track individual job execution states.

GET https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-apps/{workflow_id}/dispatch-jobs/{dispatch_job_id}

Before you begin

  1. Prepare a personal access token with read permission on the target workflow and the target workspace ID.

  2. Obtain the workflow ID and dispatch job ID from a volume or batch-file run via Start workflow job, Retry workflow jobs in batches, or View workflow jobs.

Request parameters

Replace $AI_STUDIO_API_KEY, $WORKSPACE_ID, $WORKFLOW_ID, and $DISPATCH_JOB_ID with actual values.

curl "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-apps/$WORKFLOW_ID/dispatch-jobs/$DISPATCH_JOB_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

Path parameters

Parameter

Type

Required

Description

workflow_id

string

Yes

Workflow ID that owns the dispatch job. Returns 404 if the dispatch job does not belong to this workflow or workspace.

dispatch_job_id

string

Yes

Dispatch job ID, obtained from data.workflow_run.execution_id when starting a batch-file run, data.dispatch_job_id in a batch retry response, or dispatch_job_id on a workflow job list item.

Successful response

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "dispatch_job": {
      "dispatch_job_id": "dispatch-001",
      "workflow_id": "wf-001",
      "status": "completed",
      "total_deliveries": 12,
      "pending_deliveries": 0,
      "failed_deliveries": 1
    }
  }
}

Field

Type

Description

code

string

OK when the request succeeds.

msg

string

Response status message.

data

object

Returned payload for this call.

data.dispatch_job

object

Dispatch job state and delivery counts.

data.dispatch_job.dispatch_job_id

string

Dispatch job ID.

data.dispatch_job.workflow_id

string

Associated workflow ID.

data.dispatch_job.status

string

Dispatch job status. Possible values: waiting, running, completed, failed, cancelled.

data.dispatch_job.total_deliveries

integer

Total number of file deliveries created for this dispatch job.

data.dispatch_job.pending_deliveries

integer

Number of deliveries still pending, dispatching, or waiting for retry.

data.dispatch_job.failed_deliveries

integer

Number of deliveries that failed after exhausting retries.

Error response

An error is returned when the workflow or dispatch job does not exist, the dispatch job does not belong to the specified workflow, or the caller lacks permission to read the workflow. Verify the workspace ID, workflow ID, and dispatch job ID before retrying.

{
  "code": "ErrNotFound",
  "msg": "Not Found"
}

Field

Type

Description

code

string

Error code.

msg

string

Readable error message.

Common HTTP errors

HTTP status

Error code

Common cause

Suggested action

400

ErrParamInvalid, ErrWorkspaceRequired

The target workspace header is missing or a path parameter is invalid.

Check the workspace header and the workflow ID in the path.

401

Unauthorized

Authentication credentials are missing or invalid.

Check that the personal access token is valid.

403

ErrForbidden

The current identity cannot read dispatch jobs for the target workflow.

Use an identity with workflow read permission, or request access from an administrator.

404

ErrNotFound

The workflow does not exist or is inactive, or the dispatch job does not belong to the current workspace and specified workflow.

Verify workflow_id, dispatch_job_id, and the target workspace.

500

ErrServer

Failed to read the dispatch record or persisted dispatch state is invalid.

Retain the request details and recheck the dispatch status later.

503

ErrServiceUnavailable

Authorization or storage dependencies are temporarily unavailable.

Retry the query later.

Last updated on