REST API Reference > Customer Managed REST API > Data Integration REST API
  

Data Integration REST API

The REST API resources in this section apply specifically to the Data Integration service in a Customer Managed runtime environment.
Data Integration REST API resources normally send requests to the IDMC URL. However in a Customer Managed runtime environment, the REST API calls are sent directly to the Secure Agents within that environment.
You can use the Data Integration REST API to perform the following tasks:
For more information, see Customer Managed REST API.

Jobs

Use the job resource to start or stop a task based on ID or name. You can also get the job completion status.
To start or stop a task based on an ID, you can use the eight-character object ID for the task or the federated task ID.
To find the eight-character object ID, see Tasks. However, this resource returns a task ID that you can use only to run tasks located in the Default folder.
If your organization uses projects and folders, see Lookup or Objects to retrieve the federated task ID.
For a Data Ingestion and Replication file ingestion and replication task, use the file ingestion and replication job resource. For more information, see File Ingestion and Replication REST API.

Starting a job

Use the job resource to start a job.

POST request

Use the following URI:
/saas/api/v2/job
The following table describes the attributes to use in a job object:
Field
Type
Required
Description
taskId
String
Required if taskName or taskFederatedId isn't included.
Task ID. Use taskId or taskName in the URI.
You can include this task ID when the task is located in the Default folder.
taskFederatedId
String
Required if the task isn't located in the Default folder.
Global unique identifier for the task, which includes the folder path to the task.
taskName
String
Required if taskId or taskFederatedId isn't included.
Task name. Use taskId or taskName in the URI.
taskType
String
Yes
The type of task. For Data Integration, use one of the following codes:
  • - DSS. Synchronization task.
  • - MTT. Mapping task.
  • - PCS. PowerCenter task.
runtime
No
Attribute that defines runtime properties.
parameterFileName
String
No
Parameter file name.
parameterFileDir
String
No
Parameter file directory on the Secure Agent machine.

POST response

The response returns the job object if the request is successful and an error object if an error occurs.
The following table describes the attributes in the job object:
Field
Type
Description
taskId
String
Task ID.
taskFederatedId
String
Global unique identifier (GUID) for the task, which includes the folder path to the task.
taskName
String
Task name.
taskType
String
The type of task. Returns one of the following codes for Data Integration:
  • - DSS. Synchronization task.
  • - MTT. Mapping task.
  • - PCS. PowerCenter task.
runId
Long
ID of the job.

POST request examples

To start a mapping task with ID "0100020Z000000000002", you might use the following request:
POST <agent-host-ip>:<port(9443)>/rm/saas/api/v2/job HTTP/1.1
Content-Type: application/json
Accept: application/json
RM-USER-TOKEN: <token>

{
"taskId": "0100020Z000000000002",
"taskType": "MTT",
}
To start a mapping task with the name "MappingTask1", you might use the following request:
POST <agent-host-ip>:<port(9443)>/rm/saas/ap/v2/job HTTP/1.1
Content-Type: application/json
Accept: application/json
RM-USER-TOKEN: <token>

{
"taskName": "MappingTask1",
"taskType": "MTT",
}
To start a task with ID "0100020Z000000000002" and runtime "mtTaskRuntime" you might use the following request:
POST <agent-host-ip>:<port(9443)>/rm/saas/ap/v2/job HTTP/1.1
Content-Type: application/json
Accept: application/json
RM-USER-TOKEN: <token>

{
"taskId": "0100020Z000000000002",
"taskType": "MTT",
"runtime":{"@type":"mtTaskRuntime"
}

Stopping a job

Use the job resource to stop a job.

POST request

Use the following URI:
/saas/api/v2/job/stop
The following table describes the attributes to use in a job object:
Field
Type
Required
Description
taskId
String
Required if taskName isn't included.
Task ID. Use taskId or taskName in the URI.
You can include this task ID when the task is located in the Default folder.
taskFederatedId
String
Required if the task isn't located in the Default folder.
Global unique identifier for the task, which includes the folder path to the task.
taskName
String
Required if taskId isn't included.
Task name. Use taskId or taskName in the URI.
taskType
String
Yes
The type of task. For Data Integration, use one of the following codes:
  • - DSS. Synchronization task.
  • - MTT. Mapping task.
  • - PCS. PowerCenter task.

POST response

The response returns the success object if the request is successful and an error object if an error occurs.

POST request example

To stop a task with ID "0100020Z000000000002" and task type "MTT", you might use the following request:
POST <agent-host-ip>:<port(9443)>/rm/saas/api/v2/job/stop HTTP/1.1
Content-Type: application/json
Accept: application/json
RM-USER-TOKEN: <token>

{
"@type": "job",
"taskId": "0100020Z000000000002",
"taskType": "MTT"
}
If the "taskType" parameter is omitted, a 403 error returns.

Cleanly stopping a job

Use the job resource to cleanly stop a job.

POST request

Use the following URI:
/rm/saas/api/v2/job/stop?cleanStop=true
The following table describes the attributes to use in a job object:
Field
Type
Required
Description
taskId
String
Required if taskName not included.
Task ID. Use taskId or taskName in the URI.
You can include this task ID when the task is located in the Default folder.
taskFederatedId
String
Required if the task is not located in the Default folder.
Global unique identifier for the task, which includes the folder path to the task.
taskName
String
Required if taskId not included.
Task name. Use taskId or taskName in the URI.
taskType
String
Yes
The type of task. For Data Integration, use one of the following codes:
  • - DSS. Synchronization task.
  • - MTT. Mapping task.
  • - PCS. PowerCenter task.

POST response

The response returns the success object if the request is successful and an error object if an error occurs.

POST request example

To cleanly stop a mapping task with ID "0100020Z000000000002" and task type "MTT", you might use the following request:
POST <agent-host-ip>:<port(9443)>/rm/saas/api/v2/job/stop?cleanStop=true
Content-Type: application/json
Accept: application/json
RM-USER-TOKEN: <token>

{
"@type": "job",
"taskId": "0100020Z000000000002",
"taskType": "MTT"
}

Logs for completed jobs

Use this resource to request log information for completed jobs from the Monitor service. You can also request error logs and session logs.

GET Request

You can request all of the log information or filter the log response. To request information from the log, use the following URI:
/rm/saas/api/v2/activity/activityLog
To request information for a specific log ID, use the following URI:
/rm/saas/api/v2/activity/activityLog/<id>
To request information for a specific run ID, include the run ID and task ID in the following URI:
/rm/saas/api/v2/activity/activityLog?runId=<runId>&taskId=<taskId>
Note:
The task ID is required whenever the run ID is included in a request.
To request information for a specific task, include the task ID in the following URI:
/rm/saas/api/v2/activity/activityLog?taskId=<taskId>
To specify the number of rows to skip, use the following URI:
/rm/saas/api/v2/activity/activityLog?offset=<offset>
To specify a row limit, use the following URI:
/api/v2/activity/activityLog?rowLimit=<rowLimit>
You can use any combination of these options. For example, you can use the following URI:
/rm/saas/api/v2/activity/activityLog?offset=<offset>&rowLimit=<rowLimit>&taskId=<taskId>&runId=<runId>
You can also use the activityLog resource to get a session log. To get a session log, use the following URI:
/rm/saas/api/v2/activity/activityLog/<id>/sessionLog
You can use the following optional attributes in the activityLog GET URI:
Field
Description
id
Log entry ID.
Include this attribute if you want to receive information for a specific ID.
runId
Job ID associated with the log entry ID. Whenever runId is included in a request, taskId is required.
taskId
Task ID associated with the log entry ID. If taskId is not specified, all activityLog entries for all tasks are returned.
offset
The number of rows to skip. For example, you might want to skip the first three rows.
rowLimit
The maximum number of rows to return. The maximum number you can specify is 1000.
If you omit this attribute, the activityLog returns all available rows, up to a maximum of 200 rows.

GET Response

Returns an activityLogEntry object for each row in the log or returns an activityLogEntry object for the specified ID. Returns the error object if errors occur.
When you request information for each row in the log, the activityLogEntry object includes the following attributes:
Field
Type
Description
id
String
Log entry ID.
type
String
The type of task. For Data Integration, returns one of the following codes:
  • - DSS. Synchronization task.
  • - MTT. Mapping task.
  • - PCS. PowerCenter task.
objectId
String
Task ID.
objectName
String
Name of the task.
runId
Long
ID for the task run.
agentId
String
Agent that runs the task.
runtimeEnvironmentId
String
Runtime environment that runs the task.
startTime
Date/time
Start time for the task. Uses Eastern Time Zone (ET).
endTime
Date/time
End time for the task. Uses Eastern Time Zone (ET).
startTimeUtc
Date/time
Start time for the task. Uses Coordinated Universal Time (UTC).
endTimeUtc
Date/time
End time for the task. Uses Coordinated Universal Time (UTC).
state
Short
Indicates whether the task completed successfully. Returns one of the following codes:
  • - 1. The task completed successfully.
  • - 2. The task completed with errors.
  • - 3. The task failed to complete.
failedSourceRows
Long
Number of rows that the task failed to read from the source.
successSourceRows
Long
Number of rows that the task successfully read from the source.
failedTargetRows
Long
Number of rows that the task failed to write to the target.
successTargetRows
Long
Number of rows that the task successfully wrote to the target.
scheduleName
String
Schedule name, if task was initiated by a schedule.
When you request log information for a specific ID, the activityLogEntry object includes the following attributes:
Field
Type
Description
id
String
Log entry ID.
type
String
The type of task. For Data Integration, returns one of the following codes:
  • - DSS. Synchronization task.
  • - MTT. Mapping task.
  • - PCS. PowerCenter task.
objectId
String
Task ID.
objectName
String
Name of the task.
runId
String
ID for the task run.
agentId
String
Agent that runs the task.
runtimeEnvironmentId
String
Runtime environment where the task runs.
startTime
Date/time
Start time for the task. Uses Eastern Time Zone (ET).
endTime
Date/time
End time for the task. Uses Eastern Time Zone (ET).
startTimeUtc
Date/time
Start time for the task. Uses Coordinated Universal Time (UTC).
endTimeUtc
Date/time
End time for the task. Uses Coordinated Universal Time (UTC).
state
Short
Indicates whether the task completed successfully. Returns one of the following codes:
  • - 1. The task completed successfully.
  • - 2. The task completed with errors.
  • - 3. The task failed to complete.
  • - 4. The task has not started.
UIState
Short
Used for internal purposes only.
isStopped
Boolean
Indicates whether the task was stopped by the user. A value of true is possible if the task completed with errors or failed to complete.
failedSourceRows
Long
Number of rows that the task failed to read from the source.
successSourceRows
Long
Number of rows that the task successfully read from the source.
failedTargetRows
Long
Number of rows that the task failed to write to the target.
successTargetRows
Long
Number of rows that the task successfully wrote to the target.
errorMsg
String
Error message associated with the job.
startedBy
String
User who started the task.
scheduleName
String
Schedule name, if task was initiated by a schedule.
orgId
String
Organization ID.
totalSuccessRows
Long
Total number of rows that were successfully read from the source and written to the target.
totalFailedRows
Long
Total number of rows that were not read from the source and written to the target.
logFilename
String
The name of the generated log file.
errorFilename
String
The name of the generated error file.
errorFileDir
String
The location of the error file on the Secure Agent machine.
connType
String
Connection type.
stopOnError
Boolean
Determines the runtime environment action to take when a nonfatal error occurs. Includes the following values:
  • - True. The task stops when an error occurs.
  • - False. The task continues to process when an error occurs.
items
Includes an activityLogEntryItem object for each task.
type
String
Included in the activityLogEntryItem object.
The type of task. For Data Integration, returns one of the following codes:
  • - DSS. Synchronization task.
  • - MTT. Mapping task.
  • - PCS. PowerCenter task.
objectId
String
Included in the activityLogEntryItem object.
Task ID.
objectName
String
Included in the activityLogEntryItem object.
Name of the task.
runId
String
Included in the activityLogEntryItem object.
ID for the task run.
agentId
String
Included in the activityLogEntryItem object.
Agent that ran the task.
runtimeEnvironmentId
String
Included in the activityLogEntryItem object.
Runtime environment where the task ran.
startTime
Date/time
Included in the activityLogEntryItem object.
Start time for the task. Uses Eastern Time Zone (ET).
endTime
Date/time
Included in the activityLogEntryItem object.
End time for the task. Uses Eastern Time Zone (ET).
startTimeUtc
Date/time
Included in the activityLogEntryItem object.
Start time for the task. Uses Coordinated Universal Time (UTC).
endTimeUtc
Date/time
Included in the activityLogEntryItem object.
End time for the task. Uses Coordinated Universal Time (UTC).
state
String
Included in the activityLogEntryItem object.
Indicates whether the task completed successfully. Returns one of the following codes:
  • - 1. The task completed successfully.
  • - 2. The task completed with errors.
  • - 3. The task failed to complete.
isStopped
Boolean
Included in the activityLogEntryItem object.
Indicates whether the task was stopped by the user. A value of true is possible if the task completed with errors or failed to complete.
errorMsg
String
Included in the activityLogEntryItem object.
Error message associated with the job.
connType
String
Included in the activityLogEntryItem object.
Connection type.
children
String
Included in the activityLogEntryItem object.
Returns an activityLogEntryItem object for each table in the task.
startedBy
String
User who started the task.
scheduleName
String
Schedule name, if task was initiated by a schedule.
transformationEntries
Includes information in a transformationLogEntry object for each transformation.
id
String
Included in the transformationLogEntry object.
Transformation ID.
txName
String
Included in the transformationLogEntry object.
Transformation name.
For target transformations, returns the target object name.
txType
String
Included in the transformationLogEntry object.
Transformation type.
successRows
Long
Included in the transformationLogEntry object.
Number of successful rows for the transformation.
affectedRows
Long
Included in the transformationLogEntry object.
Number of rows affected by the defined task operation.
Applies to target transformations in data transfer tasks and mapping tasks based on mappings that are not configured for full SQL ELT optimization. Doesn't apply to mappings in SQL ELT mode or advanced mappings.
failedRows
Long
Included in the transformationLogEntry object.
Number of failed rows for the transformation.
sequenceValues
Returns information generated from a task that includes the sequence generator transformation. Includes a sequenceValueLogEntry object for each transformation.
txName
String
Included in the sequenceValueLogEntry object.
Transformation name.
For target transformations, returns the target object name.
nextValue
String
Included in the sequenceValueLogEntry object.
The last value generated by the task.
inOutParameterValues
The in-out parameter values used in the task. Includes an inOutParameterValueLogEntry for each parameter.
name
String
Included in the inOutParameterValueLogEntry object.
Parameter name.
value
String
Included in the inOutParameterValueLogEntry object.
Parameter value.

GET Example

To request the first 5 rows of task ID "0100020Z000000000002", you might use the following request:
GET <agent-host-ip>:<port(9443)>/rm/saas/api/v2/activity/activityLog?taskId=0100020Z000000000002&rowLimit=5
Content-Type: application/json
Accept: application/json
RM-USER-TOKEN: <token>
A successful request returns a list: an activityLogEntry object for each entry returned from the log.
The following text is a sample return in JSON showing the first entry:
[
{
"@type": "activityLogEntry",
"id": "0100020Z000000000002",
"type": "DRS",
"objectName": "MappingTask1",
"runId": 68,
"agentId": 01000208000000000004
"runtimeEnvironmentId": "01000225000000000002",
"startTime": "2026-07-30T13:30:30.000Z",
"endTime": "2026-07-30T13:32:30.000Z",
"startTimeUtc": "2026-07-30T17:30:30.000Z",
"endTimeUtc": "2026-07-30T17:32:30.000Z",
"state": 3,
"errorMsg": "The job was stopped at user request.", startedBy System User, item attr Session Log File Name s_mtt_52tkYp7cDW8k1tfJoUwBqm_68.log and Session Log File directory $PMSessionLogDir",
},
]

To request information for log ID "b3wrn6DVwyCloYjlsMODqf" you might use the following request:
GET <agent-host-ip>:<port(9443)>/rm/saas/api/v2/activity/activityLog/b3wrn6DVwyCloYjlsMODqf
Content-Type: application/json
Accept: application/json
RM-USER-TOKEN: <token>
To request a session log for log ID "20I9ES5acHJcQwRmmjRG0s" you might use the following request:
GET <agent-host-ip>:<port(9443)>/rm/saas/api/v2/activity/activityLog/20I9ES5acHJcQwRmmjRG0s/sessionLog
Content-Type: application/json
Accept: application/json
RM-USER-TOKEN: <token>
The response body might start with the following information:
Agent Group Id: 01000225000000000002
Agent Id: 01000208000000000004
Task Name: MappingTask1
Task Type: MTT
Task Id: 0100020Z000000000002
Run Id: 71
Service Id: 01000208000000000004
Started By: System User
Run Context Type: REST_API_V2
PETL_24036 [2026-09-30 19:02:38.170] Beginning the prepare phase for the session.

Taskflows

You can use the REST API to run, stop, and monitor taskflows directly in a Customer Managed runtime environment, without routing the request through IDMC.
Taskflows REST API resources normally send requests to the IDMC URL. However in a Customer Managed runtime environment, the REST API calls are sent directly to the Secure Agents within that environment.
Note:
Linear taskflows are not supported in Customer Managed runtime environments.
You can use the Taskflows REST API to perform the following tasks:
For information about Customer Managed runtime environments, see Runtime Environments in the Administrator help.

Running a taskflow

Use the REST API to run a taskflow directly in a Customer Managed runtime environment. Use this resource to trigger taskflows from a third-party scheduler or an orchestration tool without an IDMC connection.
You can run a taskflow using the following methods:
Before you run a taskflow, verify the following prerequisites:

POST request

To run a taskflow, use the following URI:
POST https://<agent-host-ip>:<port(9443)>/rm/active-bpel/tf/<tf_api_name>
RM-USER-TOKEN: <token>
Content-Type: application/json
Example:
POST https://invtfqarh901.informatica.com:9443/rm/active-bpel/tf/<tf_api_name>
RM-USER-TOKEN:<token>

POST response

The API returns an run ID if the agent accepts the request, or an error object if the request fails.
{
"runId": "<run ID>"
}
Example:
{
    “runId”: “2019XX”
}
A 202 Accepted response means the agent accepted the job. It doesn't mean that the taskflow completed. Use the execution ID to check the run status. For more information, see Monitoring taskflow status.

Stopping a taskflow run

Use the REST API to stop a taskflow run that is in progress in a Customer Managed runtime environment.
Before you stop a run, verify the following prerequisites:

PUT request

To stop a running taskflow, use the following URI:
PUT https://<agent-host-ip>:<port(9443)>/rm/active-bpel/restadmin/processes/<run ID>/terminate?isManual=true
RM-USER-TOKEN: <token>
The request body contains the following fields:
Parameter
Type
Description
<run ID>
Number
The ID of the taskflow run to stop.
isManual
Boolean
Required. Set to true.

PUT response

The API returns the HTTP status code 204 and an empty response body if the agent accepts the request. If the request fails, the response contains the same error information as the corresponding Data Integration resource.

Resuming a suspended taskflow run

Use the REST API to resume a taskflow run that is suspended in a Customer Managed runtime environment.
To find suspended runs, query the status resource and filter by the Suspended status. For more information, see Monitoring taskflow status.

PUT request

To resume a suspended taskflow run, use the following URI:
PUT https://<agent-host-ip>:<port(9443)>/rm/active-bpel/restadmin/processes/<run ID>/resume
RM-USER-TOKEN: <token>
In the URI, <run ID> is the ID of the taskflow run to resume.

PUT response

The API returns the HTTP status code 204 and an empty response body if the agent accepts the request. The run status changes from Suspended to Running.
If the run isn't suspended, the request has no effect on the run.

Restarting a taskflow run

Use the REST API to restart a taskflow run in a Customer Managed runtime environment. The agent starts a new run of the taskflow. The original run doesn't change.
You can restart a suspended taskflow instance but not a taskflow instance that's still running.

POST request

To restart a taskflow run, use the following URI:
POST https://<agent-host-ip>:<port(9443)>/rm/active-bpel/restadmin/processes/<run ID>/restartasnew
RM-USER-TOKEN: <token>
In the URI, <run ID> is the ID of the taskflow instance to restart.

POST response

The API returns the HTTP status code 204 and an empty response body if the agent accepts the request. The response doesn't include the run ID of the new run. To find the new run, use the status resource. For more information, see Monitoring taskflow status.
If the original run is still running, the request fails with the same error that Data Integration returns.

Monitoring taskflow status

Use the status resource to monitor a taskflow running in a Customer Managed runtime environment. The request and response match those for the status resource described in Monitoring taskflow status with the status resource. The only difference is that you send the request directly to the agent, not to your IDMC URL.

GET request for a single run

To get the status of one taskflow run, use the following URI:
GET https://<agent-host-ip>:<port(9443)>/rm/active-bpel/services/tf/status/<run ID>
RM-USER-TOKEN: <token>
To include details about each subtask, add ?subtaskDetails=yes to the URI.
You can include the following optional headers. The headers apply only to requests for a single run.
Header
Description
Max-Retry
Number of times the agent retries the lookup if it doesn't find the run. Maximum value is 5.
Retry-Interval
Number of seconds between retries. Maximum value is 20.
For more information about the status parameters, see Monitoring taskflow status with the status resource
Query this resource directly on the agent to get real-time status when the agent group is disconnected from IDMC. Taskflow runs that start while the agent group is disconnected don't appear in Monitor until the Secure Agents in the Customer Managed runtime environment reconnects and synchronizes run history. Synchronization time depends on the number of runs that occurred during the disconnection.
You can't perform live job actions, such as stop or restart, against runs from Monitor in IDMC while the agent group is disconnected. To stop a run while disconnected, use the agent-side stop resource. For more information, see Stopping a taskflow run.

GET request for suspended runs

To list the taskflow runs that are suspended, use the following URI:
GET https://<agent-host-ip>:<port(9443)>/rm/active-bpel/services/tf/status?runStatus=Suspended
RM-USER-TOKEN: <token>
You can also use the startTime, endTime, offset, rowLimit, and subtaskDetails query parameters. These parameters work the same way as they do in Monitoring taskflow status with the status resource. The rowLimit value can range from 10 through 50.
A run doesn't appear in this list after you resume it or stop it.

GET response

A request for a single run returns one status object. A request for suspended runs returns an array of status objects. If no run matches, the response is HTTP status code 200 with the following body:
{
"status": "No status available"
}
The agent returns the HTTP status code 400 if the run ID isn't valid, and 500 if the agent can't read the run data. The response body contains the reason, code, detail, and message fields.

Rules and Guidelines

Consider the following rules and guidelines when you monitor taskflow runs in a Customer Managed runtime environment: