Overview Statistics API

Overview Statistics API

The Overview Statistics API provides aggregated metrics and time-series data for process instances. Endpoints use HTTP POST with a JSON body (OverviewRequest) so large lists of process keys do not hit HTTP 414 (URI Too Long).

Base Path: /overview

License: These endpoints require a valid enterprise license. Otherwise the API responds with HTTP 403.

Request body: OverviewRequest

All /overview endpoints accept the same JSON body:

Field Type Description
processKey string[] Optional. Process definition keys (omit together with version for global aggregates).
version string Optional. Process version; used with non-empty processKey.
startDate string Optional. Start of range (ISO 8601).
endDate string Optional. End of range (ISO 8601).

Rules:

  • To aggregate across all processes: send "processKey": null and "version": null (or omit both).
  • To filter by process(es): send a non-empty processKey array; version applies as in the engine.
  • If processKey is missing or empty while version is set, or keys are provided incorrectly, the server responds with an error (no process key).

Example body:

{
  "processKey": ["invoice-process"],
  "version": "1",
  "startDate": "2026-01-01T00:00:00Z",
  "endDate": "2026-01-31T23:59:59Z"
}

Instance count and KPI endpoints

These return single numbers (Integer, Long, or Double) or, for top user tasks, a JSON array.

Method Path Response type
POST /overview/started-instances Integer
POST /overview/finalized-instances Integer
POST /overview/successful-instances Integer
POST /overview/avg-process-duration Long (ms)
POST /overview/canceled-instances-internally-terminated Integer
POST /overview/canceled-instances-externally-terminated Integer
POST /overview/error-start-event-instances Integer
POST /overview/incident-instances Integer
POST /overview/completed-user-tasks-percentage Double (0–100)
POST /overview/avg-user-task-duration Long (ms)
POST /overview/top-user-tasks Array of activity instance info (allows empty processKey to scan all processes)

Example (started instances):

POST /overview/started-instances
Content-Type: application/json

{
  "processKey": ["order-process"],
  "version": "1",
  "startDate": "2026-01-01T00:00:00Z",
  "endDate": "2026-01-31T23:59:59Z"
}

Example HTTP response:

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

142

Example HTTP response (average duration, ms):

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

3600000

Example HTTP response (completed user tasks %):

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

94.5

Example HTTP response (POST /overview/top-user-tasks):

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

[
  {
    "activityId": "Task_1",
    "activityCount": 1205,
    "minDuration": 120000,
    "maxDuration": 1200000,
    "averageDuration": 300000,
    "processDefinitionKey": "invoice-process",
    "name": "Review"
  }
]

Time-series graph endpoints

Each returns an array of time buckets with instance counts.

Method Path
POST /overview/graph/started-instances
POST /overview/graph/finalized-instances
POST /overview/graph/successful-instances
POST /overview/graph/canceled-instances
POST /overview/graph/incident-instances

Example HTTP response (time-series graph):

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

[
  {
    "date": 1704067200000,
    "totalInstances": 45
  },
  {
    "date": 1704153600000,
    "totalInstances": 52
  }
]
Field Type Description
date long Bucket time (Unix epoch ms)
totalInstances int Instances in that bucket

Usage examples

Global aggregates (all processes)

curl -X POST "http://localhost:8899/overview/started-instances" \
  -H "Content-Type: application/json" \
  -d "{\"processKey\":null,\"version\":null,\"startDate\":\"2026-01-01T00:00:00Z\",\"endDate\":\"2026-01-31T23:59:59Z\"}"

Specific process and version

curl -X POST "http://localhost:8899/overview/graph/started-instances" \
  -H "Content-Type: application/json" \
  -d "{\"processKey\":[\"invoice-process\"],\"version\":\"1\",\"startDate\":\"2026-01-01T00:00:00Z\",\"endDate\":\"2026-01-31T23:59:59Z\"}"

Expect HTTP 200 and a JSON body in the shapes described under Example HTTP responses above (scalar numbers for KPI routes, array for graph routes).

Notes

  • All duration values are in milliseconds.
  • Date strings should use ISO 8601 with timezone.
  • Graph endpoints follow the same OverviewRequest rules as the KPI endpoints.

On this Page: