✨ Get KPI data with optional segmentation

GET

http://localhost:8000/api/analytics/kpis/:kpi_key

GET

/api/analytics/kpis/:kpi_key

$ curl -G http://localhost:8000/api/analytics/kpis/kpi_key \
>      -H "Authorization: Token  <api_key>" \
>      -d tz=tz

1 {
2   "kpi_key": "string",
3   "kpi_label": "string",
4   "segmentation": "none",
5   "unit": "string",
6   "by_project": {
7     "projects": [
8       {
9         "project_id": 1,
10         "project_name": "string",
11         "workspace_id": 1,
12         "workspace_name": "string"
13       }
14     ],
15     "values": [
16       1.1
17     ]
18   },
19   "by_user": {
20     "users": [
21       {
22         "user_email": "string",
23         "user_id": 1,
24         "username": "string"
25       }
26     ],
27     "values": [
28       1.1
29     ],
30     "total": 1
31   },
32   "matrix": {
33     "interval_start": [
34       "2024-01-15T09:30:00Z"
35     ],
36     "users": [
37       {
38         "user_email": "string",
39         "user_id": 1,
40         "username": "string"
41       }
42     ],
43     "values": [
44       [
45         1.1
46       ]
47     ]
48   },
49   "project_matrix": {
50     "interval_start": [
51       "2024-01-15T09:30:00Z"
52     ],
53     "projects": [
54       {
55         "project_id": 1,
56         "project_name": "string",
57         "workspace_id": 1,
58         "workspace_name": "string"
59       }
60     ],
61     "values": [
62       [
63         1.1
64       ]
65     ]
66   },
67   "time_series": {
68     "interval_start": [
69       "2024-01-15T09:30:00Z"
70     ],
71     "values": [
72       1.1
73     ]
74   },
75   "total": {
76     "unit": "string",
77     "value": 1.1
78   }
79 }

This endpoint is not available in Label Studio Community Edition. Learn more about Label Studio Enterprise

Retrieve data for a specific KPI with support for filtering and segmentation. Can segment by time (hourly, daily, weekly, monthly, yearly), by user, or both (2D matrix). If no segmentation is specified, returns a single total value. Supports filtering by projects, members, and date range. Date filters are interpreted in the specified timezone (required parameter). Maximum 50 projects allowed per request for performance reasons.

<Card href="https://humansignal.com/goenterprise"> <img style="pointer-events: none; margin-left: 0px; margin-right: 0px;" src="https://docs.humansignal.com/images/badge.svg" alt="Label Studio Enterprise badge"/> <p style="margin-top: 10px; font-size: 14px;"> This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise) </p> </Card> Retrieve data for a specific KPI with support for filtering and segmentation. Can segment by time (hourly, daily, weekly, monthly, yearly), by user, or both (2D matrix). If no segmentation is specified, returns a single total value. Supports filtering by projects, members, and date range. Date filters are interpreted in the specified timezone (required parameter). Maximum 50 projects allowed per request for performance reasons.

Authentication

AuthorizationToken

The token (or API key) must be passed as a request header. You can find your user token on the User Account page in Label Studio. Example:

curl https://label-studio-host/api/projects -H “Authorization: Token [your-token]”

The token (or API key) must be passed as a request header. You can find your user token on the User Account page in Label Studio. Example: <br><pre><code class="language-bash">curl https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>

Path parameters

kpi_keystringRequired

KPI identifier (key)

Query parameters

allbooleanOptional

When true with segment_by_user, return only members with performance data (capped). Used by Member Performance Select All discovery.

enddatetimeOptional

End date for filtering (ISO format)

membersstringOptional

Comma-separated user IDs. If empty, includes all organization members.

projectsstringOptional

Comma-separated project IDs. If empty, includes all organization projects. Maximum 50 projects allowed per request. Requests exceeding this limit will be rejected with a 400 error.

segment_by_projectbooleanOptional

Whether to segment results by project

segment_by_timeenumOptional

Time granularity for segmentation

Allowed values:

segment_by_userbooleanOptional

Whether to segment results by user

startdatetimeOptional

Start date for filtering (ISO format)

tzstringRequired

Timezone for date filtering (IANA timezone name, e.g., “America/New_York”, “UTC”). The start and end dates will be interpreted in this timezone.

Response

KPI data with requested segmentation

kpi_keystring

KPI identifier

kpi_labelstring or null

Human-readable KPI label

segmentationenum

Type of segmentation applied

none - none
time - time
user - user
project - project
matrix - matrix
project_matrix - project_matrix

unitstring

Unit of measurement: seconds, minutes, hours, count, or ratio

by_projectobject or nullOptional

Project-segmented data (compact format with parallel arrays)

by_userobject or nullOptional

User-segmented data (compact format with parallel arrays)

matrixobject or nullOptional

2D matrix (time × user) in compact format

project_matrixobject or nullOptional

2D matrix (time × project) in compact format

time_seriesobject or nullOptional

Time-segmented data (compact format with parallel arrays)

totalobject or nullOptional

Total value (no segmentation)

Errors

400

Bad Request Error

404

Not Found Error