Skip to main content

Job Endpoints

Job Endpoints and Parameters

Retrieve Details about Running Jobs

Retrieve Details about a Specific Job

Retrieve Messages of a Specific Job

Cancel a Specific Job

To learn more about the objects relations and how to use them in the API, go to the Object Relations section.

For more information about jobs, visit the Jobs: Admin Interface help page.

Retrieve Details about All Jobs

To retrieve details about all jobs and their current state, use the GET {baseURL}/v3/jobs endpoint. Use various parameters to filter the jobs you want to display.

Note

Only Curators can use this endpoint.

Parameters

  • sortField (string): Optional. Sort the results by these allowed values: CreateDate, AppName, CompletionDateTime, Priority, Status.

  • direction (string): Optional. Sort in ascending or descending order. Allowed values are: asc or desc.

  • offset (string): Optional. Enter offset for paging.

  • limit (string): Optional. Enter limit for paging.

  • priorities (string): Optional. To filter by job priorities, enter one of more of these values: Low, Medium, High, Critical, and Numeric Values.

  • statuses (string): Optional. To filter by status, enter one or more of these values: Queued, Initializing, Running, and Complete.

  • users (string): Optional. To filter by a user, enter a valid userId. Filters only if allUsers = true.

  • allUsers (boolean): Optional. To include all users, select true.

  • workflowNames (string): Optional. To filter by a workflow name, enter one or more of workflowName.

  • completedBefore (string): Optional. Returns jobs completed before the specified date. Jobs completed on the given date are excluded. The required format is yyyy-MM-dd.

  • completedAfter (string): Optional. Returns jobs completed after the specified date. Jobs completed on the given date are excluded. The required format is yyyy-MM-dd.

Request Example: cURL

curl -X 'GET' \
  'http://localhost/webapi/v3/jobs' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer BearerTokenGoesHere'

Response Example

  • 200: OK

    {
  "data": [
    {
      "jobId": "68dd3292c97fddfcc003adcb",
      "status": "Completed",
      "workflowName": "Workflow1.yxmd",
      "workflowId": "68dd32922a719467662d27c7",
      "submittedBy": "Jane Doe",
      "startTime": "2025-10-01T13:54:26Z",
      "queueTime": "2025-10-01T13:54:26Z",
      "executionTime": "00:00:02",
      "priority": "6"
    },
    {
      "jobId": "68dd3336c97fddfcc003add2",
      "status": "Completed",
      "workflowName": "Workflow1",
      "workflowId": "68dd32922a719467662d27c7",
      "submittedBy": "Jane Doe",
      "startTime": "2025-10-01T13:57:10Z",
      "queueTime": "2025-10-01T13:57:10Z",
      "executionTime": "00:00:02",
      "priority": "Low"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 50,
    "totalItems": 3,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

  • 401: Unauthorized

Retrieve Details about a Specific Job

To retrieve details about an existing job and its current state, use the GET {baseURL}/v3/jobs/{jobId} endpoint. Use various parameters to filter the jobs you want to display.

Note

Only app workflows can be used.

Users are able to see jobs run by them and jobs run on schedules shared via Collections.

Parameters

  • jobId (string): Required. Enter the Job ID for which you want to display details.

  • includeMessages (boolean): Optional. Can be left without a value. You can choose from the following values: ‘true’ and ‘false’. If this parameter is set to ‘false’, then a reduced object will be returned. When not specified, the ‘true’ value is used.

Request Example: cURL

curl -X 'GET' \
  'http://localhost/webapi/v3/jobs/66ebd18d3d6200007e000d8c?includeMessages=true' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer BearerTokenGoesHere'

Response Example

  • 200: OK

    {
  "id": "string",
  "appId": "string",
  "createDateTime": "2024-09-19T10:02:54.589Z",
  "status": "string",
  "disposition": "string",
  "outputs": [
    {
      "id": "string",
      "availableFormats": [
        "string"
      ],
      "fileName": "string"
    }
  ],
  "messages": [
    {
      "status": 0,
      "text": "string",
      "toolId": 0
    }
  ],
  "priority": "Default",
  "workerTag": "string",
  "runWithE2": true
}

  • 401: Unauthorized

  • 404: NotFound

Retrieve Messages of a Specific Job

To retrieve all messages of a specific job, use the GET {baseURL}/v3/jobs/{jobId}/messages endpoint.

Note

Only Curators can use this endpoint.

Parameters

  • jobId (string): Required. Enter the Job ID for which you want to display messages.

Request Example: cURL

curl -X 'GET' \
  'http://localhost/webapi/v3/jobs/66ebd18d3d6200007e000d8c/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer BearerTokenGoesHere'

Response Example

  • 200: OK

    {
  "status": 0,
  "text": "string",
  "toolId": 0
}

  • 401: Unauthorized

  • 404: NotFound

Cancel a Specific Job

To cancel a specific job, use the DELETE {baseURL}/v3/jobs/{jobId} endpoint. The job must be in "Queued" or "Running" state.

If you cancel a running job, it gets canceled. If you cancel a queued job, it gets deleted.

Note

Curators can cancel any jobs.

Other roles can cancel jobs they have created, triggered, or scheduled. It includes jobs shared with them through Collections, even if they are not the job owner.

Parameters

  • jobId (string): Required. Enter the Job ID you want to cancel.

Request Example: cURL

curl -X 'DELETE' \
  'http://localhost/webapi/v3/jobs/678f97baa15300008c0039fc' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer BearerTokenGoesHere'

Response Example

  • 200: OK

    • Response when you cancel a running job:

      {
  "message": "Cancelled Successfully."
}

    • Response when you cancel a queued job:

      {
  "message": "Deleted Successfully."
}

  • 400: BadRequest

    • Response when the job is not in ‘Queued’ or ‘Running’ state:

      {
  "message": "This job is not in 'Queued' or 'Running' state."
}

    • Response when the user making the API call does not have permission to cancel the job:

      {
  "message": "You do not have permission to cancel this job."
}

  • 401: Unauthorized

  • 404: NotFound

Objects Relations

If you want to get information about a specific job, you need a jobId. To obtain this jobId, use the GET {baseURL}/v3/workflows/{workflowId}/jobs endpoint. For more information about this endpoint, see the Workflow Endpoints help page.Workflow Endpoints

Postman Requests

To know more about Postman requests, visit the How to Use Postman help page.

In this section: