Skip to main content

List the records behind a KPI

POST 
/report/records

List the records one /report/kpi value counts, with who each was credited to and why. Use it to explain a number from terros report kpi: pass one KPI value as kpi (CLI: --kpi), the same filter, grouping, and searchByCurrentStatus, and the row's key as groupKey (for a user grouping, the user ID). It applies the same permissions, team limits, and filters as /report/kpi, so for count KPIs total equals the KPI value. records lists only what you could already list: an account you can view through /account/list, a task you can list through /task/list, and recordings only for Terros users, as /recording/list allows. The rest are counted in withheld. So a caller with narrow list permissions, such as a rep with self account access, does not see an account that was credited to them but has since been reassigned. An admin, or anyone whose account:list covers the accounts, gets the full record set with nothing withheld.

Supported KPIs: workflow stage counts (account|S.xxxxxxxx|count, actor|…, setter|…, closer|…), action counts (action|A.xxxxxxxx|count, action.count), task.overdue, recording.activeHours (each record's value is its seconds), and recording.activeUsers (one active recording per user, so total is the distinct-user count). Other KPIs return an InvalidRequest error.

Setter and closer counts credit whoever was setter or closer when the account entered the stage, so an account reassigned after it closed still counts for the closer at the time, and one handed to another closer before it closed counts for that closer. Each stage record is one stage entry: an account that entered the stage twice in the range appears twice, as it counts twice in the KPI.

Records come back oldest first (overdue tasks by when they were opened), up to limit (default 500, maximum 10000); total is always the full count. Visibility is checked on the first limit matches only. When more match, truncated is true (raise limit to read them), withheld is a lower bound, and hidden records among those matches can leave records shorter than limit.

Example (synthetic IDs): terros report records --kpi 'closer|S.xxxxxxxx|count' --grouping '{"type":"user"}' --groupKey U.xxxxxxxx --filter.users '["U.xxxxxxxx"]' --filter.startDate 2026-01-01 --filter.endDate 2026-12-31

Request​

Responses​

Success