Process Analysis API

The Process Analysis API provides detailed activity-level metrics, bottleneck detection, outlier identification, and duration analysis for individual process definitions.

Base Path: /process-analysis

License: These endpoints require a valid enterprise license (HTTP 403 otherwise).

State filter: For most operations you must pass one or more states query parameters (Spring style: repeat states= for each value, e.g. states=ACTIVE&states=COMPLETED). Values are engine state names.

Endpoints

GET /process-analysis/activity

Returns activity-level statistics for a process.

Purpose: Get execution statistics for each activity in a process, including average duration, execution count, min/max durations.

Parameters:

Parameter	Type	Required	Description
`processKey`	string	Yes	Process definition key
`version`	string	Yes	Process version
`states`	string[]	Yes	At least one instance state
`startDate`	string	No	Start date (ISO 8601)
`endDate`	string	No	End date (ISO 8601)

Example HTTP response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "successFullInstances": 1205,
  "averageInstanceDuration": 3600000,
  "activityInstances": [
    {
      "activityId": "Task_1",
      "activityCount": 1205,
      "minDuration": 120000,
      "maxDuration": 1200000,
      "averageDuration": 300000,
      "processDefinitionKey": "invoice-process",
      "name": "Review Invoice"
    },
    {
      "activityId": "Task_2",
      "activityCount": 1205,
      "minDuration": 60000,
      "maxDuration": 600000,
      "averageDuration": 150000
    }
  ]
}

Response Fields:

Field	Type	Description
`successFullInstances`	int	Number of successful process instances
`averageInstanceDuration`	long	Average process instance duration (ms)
`activityInstances`	array	List of activity statistics
`activityInstances[].activityId`	string	BPMN activity identifier
`activityInstances[].activityCount`	int	Number of times activity executed
`activityInstances[].minDuration`	long	Minimum duration (ms)
`activityInstances[].maxDuration`	long	Maximum duration (ms)
`activityInstances[].averageDuration`	long	Average duration (ms)
`activityInstances[].processDefinitionKey`	string	Present when provided by the backend
`activityInstances[].name`	string	Human-readable activity label when available

GET /process-analysis/activity-duration

Returns duration between two specific activities.

Purpose: Calculate the average time elapsed between a start activity and an end activity within process instances.

Parameters:

Parameter	Type	Required	Description
`processKey`	string	Yes	Process definition key
`version`	string	Yes	Process version
`startActivityId`	string	Yes	Start activity BPMN ID
`endActivityId`	string	Yes	End activity BPMN ID
`states`	string[]	Yes	At least one instance state
`startDate`	string	No	Start date (ISO 8601)
`endDate`	string	No	End date (ISO 8601)

Example HTTP response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "startActivityId": "Task_1",
  "endActivityId": "Task_5",
  "averageDuration": 2100000
}

Response Fields:

Field	Type	Description
`startActivityId`	string	Start activity identifier
`endActivityId`	string	End activity identifier
`averageDuration`	long	Average duration between activities (ms)

GET /process-analysis/outliers

Returns outlier process instances based on duration thresholds.

Purpose: Identify process instances that took significantly longer or shorter than normal, useful for finding problem instances.

Parameters:

Parameter	Type	Required	Description
`processKey`	string	Yes	Process definition key
`version`	string	Yes	Process version
`states`	string[]	Yes	At least one instance state
`lowerThresholdIqr`	long	Yes	Lower threshold for outliers (ms)
`upperThresholdIqr`	long	Yes	Upper threshold for outliers (ms)
`minResults`	int	Yes	Minimum number of results to return
`maxResults`	int	Yes	Maximum number of results to return
`startDate`	string	No	Start date (ISO 8601)
`endDate`	string	No	End date (ISO 8601)

Example HTTP response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "procInstId": "pi-12345",
    "startTime": 1704067200000,
    "procDuration": 7200000,
    "diffFromMean": 3600000,
    "longestActivity": "Task_3",
    "activityDuration": 3000000
  },
  {
    "procInstId": "pi-12346",
    "startTime": 1704070800000,
    "procDuration": 9000000,
    "diffFromMean": 5400000,
    "longestActivity": "Task_2",
    "activityDuration": 4500000
  }
]

Response Fields:

Field	Type	Description
`procInstId`	string	Process instance ID
`startTime`	long	Instance start time (ms, Unix epoch)
`procDuration`	long	Total process duration (ms)
`diffFromMean`	long	Difference from mean duration (ms)
`longestActivity`	string	Activity with longest duration
`activityDuration`	long	Duration of longest activity (ms)

GET /process-analysis/duration

Returns duration distribution for process instances.

Purpose: Get histogram-style data showing the distribution of process instance durations.

Parameters:

Parameter	Type	Required	Description
`processKey`	string	Yes	Process definition key
`version`	string	Yes	Process version
`states`	string[]	Yes	At least one instance state
`startDate`	string	No	Start date (ISO 8601)
`endDate`	string	No	End date (ISO 8601)

Example HTTP response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "date": 1800000,
    "totalInstances": 120
  },
  {
    "date": 3600000,
    "totalInstances": 850
  },
  {
    "date": 5400000,
    "totalInstances": 200
  },
  {
    "date": 7200000,
    "totalInstances": 35
  }
]

Response Fields:

Field	Type	Description
`date`	long	Duration bucket (ms)
`totalInstances`	int	Number of instances in this duration range

GET /process-analysis/thresholds

Returns calculated threshold values for outlier detection.

Purpose: Get the lower and upper threshold values based on statistical analysis (typically using IQR method).

Parameters:

Parameter	Type	Required	Description
`processKey`	string	Yes	Process definition key
`version`	string	Yes	Process version
`startDate`	string	No	Start date (ISO 8601)
`endDate`	string	No	End date (ISO 8601)

Example HTTP response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "lowerThreshold": 1200000,
  "upperThreshold": 5400000
}

Response Fields:

Field	Type	Description
`lowerThreshold`	long	Lower duration threshold (ms)
`upperThreshold`	long	Upper duration threshold (ms)

GET /process-analysis/version-duration

Returns duration statistics grouped by process version.

Purpose: Compare performance across different versions of the same process.

Parameters:

Parameter	Type	Required	Description
`processKey`	string	Yes	Process definition key
`states`	string[]	Yes	At least one instance state

Example HTTP response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "version": 1,
    "avgDurationMs": 3600000,
    "minDurationMs": 1200000,
    "maxDurationMs": 7200000,
    "totalInstances": 500
  },
  {
    "version": 2,
    "avgDurationMs": 3000000,
    "minDurationMs": 1000000,
    "maxDurationMs": 6000000,
    "totalInstances": 705
  }
]

Response Fields:

Field	Type	Description
`version`	int	Process version number
`avgDurationMs`	long	Average duration (ms)
`minDurationMs`	long	Minimum duration (ms)
`maxDurationMs`	long	Maximum duration (ms)
`totalInstances`	int	Total instances for this version

Usage Examples

Get Activity Statistics

curl -G "http://localhost:8899/process-analysis/activity" \
  --data-urlencode "processKey=invoice-process" \
  --data-urlencode "version=1" \
  --data-urlencode "states=COMPLETED"

Get Duration Between Activities

curl -G "http://localhost:8899/process-analysis/activity-duration" \
  --data-urlencode "processKey=invoice-process" \
  --data-urlencode "version=1" \
  --data-urlencode "startActivityId=Task_1" \
  --data-urlencode "endActivityId=Task_5" \
  --data-urlencode "states=COMPLETED"

Get Outliers

curl -G "http://localhost:8899/process-analysis/outliers" \
  --data-urlencode "processKey=invoice-process" \
  --data-urlencode "version=1" \
  --data-urlencode "states=COMPLETED" \
  --data-urlencode "lowerThresholdIqr=1000000" \
  --data-urlencode "upperThresholdIqr=5000000" \
  --data-urlencode "minResults=5" \
  --data-urlencode "maxResults=50"

Get Duration Distribution

curl -G "http://localhost:8899/process-analysis/duration" \
  --data-urlencode "processKey=invoice-process" \
  --data-urlencode "version=1" \
  --data-urlencode "states=COMPLETED" \
  --data-urlencode "startDate=2026-01-01T00:00:00Z" \
  --data-urlencode "endDate=2026-01-31T23:59:59Z"

Get Version Comparison

curl -G "http://localhost:8899/process-analysis/version-duration" \
  --data-urlencode "processKey=invoice-process" \
  --data-urlencode "states=COMPLETED"

Each command above returns HTTP 200 with Content-Type: application/json when the license is valid and parameters are accepted; the JSON matches the example HTTP response for that endpoint in the sections above.

Notes

All duration values are in milliseconds
The processKey and version parameters are required for all endpoints except version-duration, which only needs processKey and states
Pass at least one states value on /activity, /activity-duration, /outliers, /duration, and /version-duration
Thresholds are typically calculated using the IQR (Interquartile Range) method
Activity IDs correspond to BPMN element IDs in the process definition
Returns empty array or null if no matching process is found

Process Analysis API