REST API Reference > Cloud Data Integration for PowerCenter (CDI-PC) REST API > Runtime and Jobs
  

Runtime and Jobs

Enter a short description of the concept here (required).
This is the start of the concept.

Retrieve Job Summary for a Conversion Task Run

Retrieves the job summary for a specific conversion or bulk conversion task run.

API request

To retrieve Job Summary for a Conversion Task Run, send a GET request to the following API endpoint:
GET /public/api/v2/jobsummary/task('{taskId}')/run('{runId}')

Request parameters

Path parameters
The following table describes the path parameters that you specify in the API request:
Name
Type
Required
Description
taskId
String
Required
Unique identifier for the Conversion or BulkConversion task whose job summary you want to retrieve.
runId
String
Required
Unique identifier for the specific run of the task. Used to scope the job summary response to a single execution instance of the specified task.
Query parameters
No parameter.
Body Parameters
This endpoint does not require any body parameters.

Request headers

The following table describes the headers that you specify in the API request:
Name
Required or Optional
Description
Accept
Optional
Response media types, e.g., application/json.

Response parameters

The following table describes the parameters that are returned by the API:
Name
Type
Description
task_overview
Object
Object containing high-level metadata about the task run, including timing, status, and execution context.
task_overview.task_type
String
Type of task that was executed, such as a conversion or bulk conversion task.
task_overview.category_type
String
Category classification of the task, indicating the broad operation group it belongs to.
task_overview.started_by
String
Email address or username of the user who initiated the task run.
task_overview.start_time
String
ISO 8601 timestamp indicating when the task run began.
task_overview.end_time
String
ISO 8601 timestamp indicating when the task run completed.
task_overview.duration
Integer
Total elapsed time of the task run, in seconds.
task_overview.runtime_environment
String
Name of the runtime environment in which the task was executed.
task_overview.secure_agent
String
Name or identifier of the secure agent that processed the task run.
task_overview.task_name
String
Display name of the task that was executed.
task_overview.location
String
Project and folder path where the task is stored.
task_overview.instance_id
Integer
Unique numeric identifier for this specific task run instance.
task_overview.status
String
Completion status of the task run, such as SUCCESS or FAILED.
task_overview.error_message
String
Error message describing the reason for failure, or null if the task run succeeded.
task_details
Object
Object containing additional details specific to the task type, such as repository, asset type, and operation.
workflow_summary
Object
Object containing aggregate counts of workflow outcomes for the task run.
workflow_summary.succeeded
Integer
Number of workflow items that completed successfully during the task run.
workflow_summary.failed
Integer
Number of workflow items that failed during the task run.
paramFile
Object
Object containing details about the parameter file used during the task run, such as total and overridden parameter counts.

Sample request

The following is a sample request based on the values provided:

curl -X GET \
"/workbench-service/public/api/v2/jobsummary/task('string')/run('string')"

Sample response

200 OK
{
"task_overview": {
"task_type": "string",
"category_type": "string",
"started_by": "string",
"start_time": "string",
"end_time": "string",
"duration": 0,
"runtime_environment": "string",
"secure_agent": "string",
"task_name": "string",
"location": "string",
"instance_id": 0,
"status": "string",
"error_message": "string"
},
"task_details": {},
"workflow_summary": {
"succeeded": 0,
"failed": 0
},
"paramFile": {}
}
400 Bad Request
{
"message": "Bad request \u2013 invalid task id or run id"
}
401 Unauthorized
{
"message": "Unauthorized \u2013 missing or invalid session credentials"
}
404 Not Found
{
"message": "Task or run not found"
}
500 Internal Server Error
{
"message": "Internal server error while fetching job summary"
}

Stop a running task instance

Stops an active run of a specified task.

API request

To stop a running task instance, send a POST request to the following API endpoint:
POST /public/api/v2/runtime/stop/task('{taskId}')/run('{runId}')

Request parameters

Path parameters
The following table describes the path parameters that you specify in the API request:
Name
Type
Required
Description
taskId
String
Required
Unique identifier for the task to be stopped.
runId
String
Required
Unique identifier for a specific run instance of the task. Used together with taskId to target the exact execution to stop.
Query parameters
No parameter.
Body Parameters
This endpoint does not require any body parameters.

Request headers

The following table describes the headers that you specify in the API request:
Name
Required or Optional
Description
Accept
Optional
Response media types, e.g., application/json.

Response parameters

The following table describes the parameters that are returned by the API:
Name
Type
Description
message
String
Confirmation message indicating the task run was stopped successfully.

Sample request

The following is a sample request based on the values provided:

curl -X POST \
"/workbench-service/public/api/v2/runtime/stop/task('string')/run('string')"

Sample response

200 OK
{
"message": "Task stopped successfully"
}
400 Bad Request
{
"message": "Bad request \u2013 invalid parameters or insufficient privileges"
}
401 Unauthorized
{
"message": "Unauthorized \u2013 missing or invalid session credentials"
}
500 Internal Server Error
{
"message": "Internal server error while stopping task"
}

Retrieve Step Status for a Task Run

Retrieves the step-level execution status for a specific task run.

API request

To retrieve Step Status for a Task Run, send a GET request to the following API endpoint:
GET /public/api/v2/runtime/stepstatus/task('{taskId}')/run('{runId}')

Request parameters

Path parameters
The following table describes the path parameters that you specify in the API request:
Name
Type
Required
Description
taskId
String
Required
Unique identifier for the task whose step status is being retrieved.
runId
String
Required
Unique identifier for a specific instance of a task run. Used together with taskId to scope the step status response to a single execution.
Query parameters
No parameter.
Body Parameters
This endpoint does not require any body parameters.

Request headers

The following table describes the headers that you specify in the API request:
Name
Required or Optional
Description
Accept
Optional
Response media types, e.g., application/json.

Response parameters

The following table describes the parameters that are returned by the API:
Name
Type
Description
taskId
String
Unique identifier for the task.
runId
Integer
Numeric identifier for the specific task run instance.
orgId
String
Unique identifier for the organization associated with the task run.
taskType
String
Category of the task, such as CONVERSION.
steps
Array
List of individual steps executed during the task run, each with its own status and timing details.
steps.step
String
Name of the individual step within the task run.
steps.status
String
Current execution status of the step, such as COMPLETED or RUNNING.
steps.startTime
String
ISO 8601 timestamp indicating when the step began execution.
steps.endTime
String
ISO 8601 timestamp indicating when the step finished execution, or an empty string if the step is still running.
steps.message
String
Additional detail or status message associated with the step, or an empty string if no message is available.
compositeSteps
Array
List of composite steps that group one or more individual steps under a single logical operation.
compositeSteps.stepName
String
Name of the composite step that groups related individual steps.
compositeSteps.steps
Array
List of individual step names included within the composite step.
compositeSteps.status
String
Current execution status of the composite step, such as COMPLETED or RUNNING.
compositeSteps.startTime
String
ISO 8601 timestamp indicating when the composite step began execution.
compositeSteps.endTime
String
ISO 8601 timestamp indicating when the composite step finished execution, or an empty string if the composite step is still running.

Sample request

The following is a sample request based on the values provided:

curl -X GET \
"/workbench-service/public/api/v2/runtime/stepstatus/task('string')/run('string')"

Sample response

200 OK
{
"taskId": "string",
"runId": 0,
"orgId": "string",
"taskType": "string",
"steps": [
{
"step": "string",
"status": "string",
"startTime": "string",
"endTime": "string",
"message": "string"
}
],
"compositeSteps": [
{
"stepName": "string",
"steps": [
"string"
],
"status": "string",
"startTime": "string",
"endTime": "string"
}
]
}
400 Bad Request
{
"message": "Bad request \u2013 invalid task id or run id"
}
401 Unauthorized
{
"message": "Unauthorized \u2013 missing or invalid session credentials"
}
404 Not Found
{
"message": "Task run not found"
}
500 Internal Server Error
{
"message": "Internal server error while retrieving step status"
}

Retrieve Runtime Status for a Task Run

Retrieves the runtime status of a specific task run.

API request

To retrieve Runtime Status for a Task Run, send a GET request to the following API endpoint:
GET /public/api/v2/runtime/status/task('{taskId}')/run('{runId}')

Request parameters

Path parameters
The following table describes the path parameters that you specify in the API request:
Name
Type
Required
Description
taskId
String
Required
Unique identifier for the task whose runtime status you want to retrieve.
runId
String
Required
Unique identifier for a specific instance of a task run. Used alongside taskId to scope the runtime status response to a single execution of the task.
Query parameters
No parameter.
Body Parameters
This endpoint does not require any body parameters.

Request headers

The following table describes the headers that you specify in the API request:
Name
Required or Optional
Description
Accept
Optional
Response media types, e.g., application/json.

Response parameters

The following table describes the parameters that are returned by the API:
Name
Type
Description
taskId
String
Unique identifier for the task associated with this run.
runId
Integer
Numeric identifier for this specific instance of the task run.
orgId
String
Unique identifier for the organization that owns the task.
taskType
String
Category of the task, such as CONVERSION.
status
String
Current execution state of the task run, such as RUNNING.
startTime
String
ISO 8601 timestamp indicating when the task run began.
endTime
String
ISO 8601 timestamp indicating when the task run completed, or an empty string if the run is still in progress.
objectsProcessed
Integer
Number of objects processed by the task run up to the time of the response.
createdBy
String
Email address of the user who created the task.
errorMessage
String
Description of the error encountered during the task run, or null if no error occurred.

Sample request

The following is a sample request based on the values provided:

curl -X GET \
"/workbench-service/public/api/v2/runtime/status/task('string')/run('string')"

Sample response

200 OK
{
"taskId": "0100000B00000000001A",
"runId": 1001,
"orgId": "a1b2c3d4",
"taskType": "CONVERSION",
"status": "RUNNING",
"startTime": "2025-03-15T10:30:00Z",
"endTime": "2025-03-15T11:45:00Z",
"objectsProcessed": 150,
"createdBy": "admin@example.com",
"errorMessage": "Connection timeout to source repository"
}
400 Bad Request
{
"message": "Bad request \u2013 invalid task id or run id"
}
401 Unauthorized
{
"message": "Unauthorized \u2013 missing or invalid session credentials"
}
404 Not Found
{
"message": "Task run not found"
}
500 Internal Server Error
{
"message": "Internal server error while retrieving runtime status"
}

Retrieve runtime status for all tasks

Retrieves the runtime status for all tasks across the organization.

API request

To retrieve runtime status for all tasks, send a GET request to the following API endpoint:
GET /public/api/v2/runtime/status/tasks

Request parameters

Path parameters
No parameter.
Query parameters
The following table describes the query parameters that you specify in the API request:
Name
Type
Required
Description
page
Integer
Optional
Zero-based page number for paginating through the list of task runtime statuses. Defaults to 0 if not provided.
pageSize
Integer
Optional
Number of task status records to return per page. Defaults to 50 if not specified.
Body Parameters
This endpoint does not require any body parameters.

Request headers

The following table describes the headers that you specify in the API request:
Name
Required or Optional
Description
Accept
Optional
Response media types, e.g., application/json.

Response parameters

The following table describes the parameters that are returned by the API:
Name
Type
Description
total
Integer
Total number of task status records returned across all pages.
tasks
Array
List of task runtime status entries returned for the current page.
tasks.taskId
String
Unique identifier for the task.
tasks.runId
Integer
Unique numeric identifier for the task run instance.
tasks.orgId
String
Unique identifier for the organization associated with the task.
tasks.taskType
String
Category of the task, such as CONVERSION or BulkUpdateTask.
tasks.status
String
Current runtime status of the task, such as RUNNING or COMPLETED.
tasks.startTime
String
ISO 8601 timestamp indicating when the task run started.
tasks.endTime
String
ISO 8601 timestamp indicating when the task run completed, or an empty string if the task is still running.
tasks.objectsProcessed
Integer
Number of objects processed by the task during the current run.
tasks.createdBy
String
Email address of the user who created the task.
tasks.errorMessage
String
Error message describing the failure reason if the task encountered an error, or null if no error occurred.

Sample request

The following is a sample request based on the values provided:

curl -X GET \
"/workbench-service/public/api/v2/runtime/status/tasks?page=0 pageSize=0"

Sample response

200 OK
{
"total": 0,
"tasks": [
{
"taskId": "0100000B00000000001A",
"runId": 1001,
"orgId": "a1b2c3d4",
"taskType": "CONVERSION",
"status": "RUNNING",
"startTime": "2025-03-15T10:30:00Z",
"endTime": "2025-03-15T11:45:00Z",
"objectsProcessed": 150,
"createdBy": "admin@example.com",
"errorMessage": "Connection timeout to source repository"
}
]
}
400 Bad Request
{
"message": "Bad request \u2013 invalid parameters"
}
401 Unauthorized
{
"message": "Unauthorized \u2013 missing or invalid session credentials"
}
404 Not Found
{
"message": "No task statuses found"
}
500 Internal Server Error
{
"message": "Internal server error while retrieving task statuses"
}

Download Task Run Artifacts

Retrieves output runtime artifacts for a specific Asset Conversion or Bulk Conversion task run.

API request

To download Task Run Artifacts, send a GET request to the following API endpoint:
GET /public/api/v2/download/task('{taskId}')/run('{runId}')/('{downloadType}')

Request parameters

Path parameters
The following table describes the path parameters that you specify in the API request:
Name
Type
Required
Description
taskId
String
Required
Unique identifier for the Asset Conversion or Bulk Conversion task whose run artifacts you want to download.
runId
String
Required
Unique identifier for the specific run of the task from which output artifacts are downloaded.
downloadType
String
Required
Controls which category of output files is included in the download response. Accepted values are download_all, download_logs, download_reports, and download_input.
Query parameters
No parameter.
Body Parameters
This endpoint does not require any body parameters.

Request headers

The following table describes the headers that you specify in the API request:
Name
Required or Optional
Description
Accept
Optional
Response media types, e.g., application/json.

Response parameters

The following table describes the parameters that are returned by the API:
Name
Type
Description
message
String
Binary file contents returned as a downloadable artifact, such as a zip archive or xlsx file.

Sample request

The following is a sample request based on the values provided:

curl -X GET \
"/workbench-service/public/api/v2/download/task('string')/run('string')/('string')"

Sample response

200 OK
{
"message": "Binary file contents (zip / xlsx / etc.)"
}
400 Bad Request
{
"message": "Bad request \u2013 invalid task id, run id, or download type"
}
401 Unauthorized
{
"message": "Unauthorized \u2013 missing or invalid session credentials"
}
404 Not Found
{
"message": "Task or run not found"
}
500 Internal Server Error
{
"message": "Internal server error while downloading files"
}