Filtering and Retrieving KPI Data
The Robotiq.ai KPI API allows you to search and filter KPI data collected during your process runs. Instead of retrieving all KPI data at once, you can narrow down the results by specifying a time range, execution stage, process, department, or specific KPI item names. This makes it easier to analyze exactly the data you need without overloading your reports or dashboards.
How it Works
The KPI search endpoint accepts a set of filters in the request body and returns a paginated list of KPI items that match your criteria. Because KPI data can grow quickly over time, a time range and execution stage are always required - this ensures your requests stay fast and return only relevant results.
Step 1: Build Your Request
- Send a POST request to:
https://api.robotiq.ai/{tenantName}/kpi/item/search
- Authorization:
Bearer Token
- Body:
The request body must be sent as JSON. In the request body, specify your filters. The only two required fields are fromUTC (start time) and jobStage (execution stage). Everything else is optional and can be combined to narrow down your results further.
Here is an example request body:
{
"fromUTC": "2026-05-01",
"toUTC": "2026-05-31",
"jobStage": "PRODUCTION",
"processInfoIds": ["6561ac92-80d2-4906-9dd7-2fcc09bb61f7"],
"names": ["Kpi_value1", "Kpi_value2"],
"pageNum": 2
}
Step 2: Understand the Filters
| Field | Type | Description | Required |
| fromUTC | date | The start of the time range you want to retrieve data for. | Yes |
| toUTC | date | The end of the time range. If not provided, all data from fromUTC onwards will be returned. | No |
| jobStage | string or integer | The stage in which the process was executed. | Yes |
| departmentIds | array of GUIDs | Limits results to specific departments. | No |
| processInfoIds | array of GUIDs | Limits results to specific processes. | No |
| jobIds | array of GUIDs | Limits results to specific job runs. | No |
| names | array of strings | Filters by the name of the KPI item. | No |
| pageNum | integer | The page number you want to retrieve. Starts at 1. | No |
| pageSize | integer | The number of results per page. Default value is 10. | No |
Step 3: Validation Rules
Required Fields
The following fields are mandatory:
- fromUTC
- jobStage
JobStage Validation
Supported values:
| DEVELOPMENT | 0 |
| TEST | 1 |
| PRODUCTION | 2 |
Both job stage names and numeric values are supported.
Stage restrictions
When jobStage is set to DEVELOPMENT, filtering by jobIds is not allowed. Development runs are not associated with Jobs and therefore cannot be filtered by jobIds.
Collection Limits
The following filters allow a maximum of 10 values:
- processInfoIds
- departmentIds
- jobIds
- names
Mutually Exclusive Filters
Only one of the following filters may be provided in a single request:
- processInfoIds
- departmentIds
- jobIds
Filtering by jobIds already implies a specific process and department, so combining it with processInfoIds or departmentIds would be redundant - similarly, if you filter by departmentIds, you are already scoping results to a broader level that makes specifying individual processes or jobs unnecessary.
Pagination Limits
- pageNum must be 1 or greater (default value is 1)
- pageSize must be between 1 and 999 (default value is 10)
If the request fails any validation rule, the API will return a 400 Bad Request response with a corresponding error message describing the validation issue.
Step 4: Understanding the Response
A successful request returns a JSON object containing a list of KPI items and pagination data. Each KPI item in the response represents a single recorded KPI entry for a specific process execution.
| Field | Description |
| id | Unique identifier of the KPI item |
| tenantId | Your organization identifier |
| processId | Identifier of the specific process run that generated this KPI item |
| departmentId | Identifier of the department the process belongs to |
| processInfoId | Identifier of the process definition (corresponds to the "PROCESS ID" value that can be found in the HQ under the process details section) |
| name | Name of the KPI item as configured in the process |
| value | Measured KPI value |
| createdAtUtc | Represents the exact moment the KPI item was created, stored in Coordinated Universal Time (UTC) |
| category | Category assigned to the KPI item in the process |
| jobStage | Execution stage: DEVELOPMENT, TEST, or PRODUCTION |
| jobId | Identifier of the scheduled job that triggered the process run. This field is null for development runs |
| robotId | Identifier of the robot that executed the process. This field is null for development runs |
| pageNum | Current page number returned in this response |
| pageItemNum | Number of items returned in the current response page |
| totalCount | Total number of KPI items that match the filter criteria across all pages |
Legacy Robot Behavior Note
Robots that have not been updated to the latest version will always set jobStage to PRODUCTION, regardless of the actual execution environment. Additionally, when a process is executed in development mode, processInfoId will be equal to processId instead of the correct process definition identifier, and both jobId and robotId will be returned as null for all KPI items.
Need Help?
Can't find what you're looking for? Join the Robotiq Community to get help from other users and the Robotiq team.