---
title: "✨ Get KPI data with optional segmentation"
method: GET
path: "/api/analytics/kpis/{kpi_key}"
tags: ["Analytics"]
---

# ✨ Get KPI data with optional segmentation

`GET /api/analytics/kpis/{kpi_key}`

<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.

## Path parameters

- `kpi_key` string, required

## Query parameters

- `end` string, date-time
- `members` string
- `projects` string
- `segment_by_project` boolean
- `segment_by_time` 'daily' | 'hourly' | 'monthly' | 'weekly' | 'yearly'
- `segment_by_user` boolean
- `start` string, date-time
- `tz` string, required

## Response `200`

KPI data with requested segmentation

- KPIDetailResponse — Response serializer for KPI detail endpoint. Structure varies based on segmentation parameters.
  - `by_project` KPIProjectSegment — Serializer for project-segmented KPI data (compact format). Returns parallel arrays: projects and values. Note: Values can be numbers (for count/time/ratio KPIs) or strings (for category KPIs like project_state).
    - `projects` KPIProjectInfo[], required — Array of project information
      - `project_id` integer, required — Project ID
      - `project_name` string, required — Project name
      - `workspace_id` integer, required — Workspace ID
      - `workspace_name` string, required — Workspace name
    - `values` union[], required — Array of KPI values, one per project (parallel to projects array). Can be numbers or strings depending on KPI type.
      - union
        - number
        - string
  - `by_user` KPIUserSegment — Serializer for user-segmented KPI data (compact format). Returns parallel arrays: users and values.
    - `users` KPIUserInfo[], required — Array of user information
      - `user_email` string, email, required — User email
      - `user_id` integer, required — User ID
      - `username` string, required — Username
    - `values` number[], required — Array of KPI values, one per user (parallel to users array)
  - `kpi_key` string, required — KPI identifier
  - `kpi_label` string, nullable, required — Human-readable KPI label
  - `matrix` KPIMatrixSegment — Serializer for 2D matrix segmentation (time × user) in compact format. Returns a 2D array where values[user_index][time_index] corresponds to users[user_index] at interval_start[time_index].
    - `interval_start` string[], required — Array of time period start timestamps
    - `users` KPIUserInfo[], required — Array of user information
      - `user_email` string, email, required — User email
      - `user_id` integer, required — User ID
      - `username` string, required — Username
    - `values` array[], required — 2D array of values: values[user_index][time_index]
      - number[]
  - `project_matrix` KPIProjectMatrixSegment — Serializer for 2D matrix segmentation (time × project) in compact format. Returns a 2D array where values[project_index][time_index] corresponds to projects[project_index] at interval_start[time_index].
    - `interval_start` string[], required — Array of time period start timestamps
    - `projects` KPIProjectInfo[], required — Array of project information
      - `project_id` integer, required — Project ID
      - `project_name` string, required — Project name
      - `workspace_id` integer, required — Workspace ID
      - `workspace_name` string, required — Workspace name
    - `values` array[], required — 2D array of values: values[project_index][time_index]
      - number[]
  - `segmentation` 'none' | 'time' | 'user' | 'project' | 'matrix' | 'project_matrix', required — * `none` - none * `time` - time * `user` - user * `project` - project * `matrix` - matrix * `project_matrix` - project_matrix
  - `time_series` KPITimeSegment — Serializer for time-segmented KPI data (compact format). Returns parallel arrays: interval_start and values.
    - `interval_start` string[], required — Array of time period start timestamps
    - `values` number[], required — Array of KPI values, one per time period (parallel to interval_start)
  - `total` KPIValue — Serializer for a single KPI value (no segmentation).
    - `unit` string, required — Unit of measurement: seconds, minutes, hours, count, or ratio
    - `value` number, double, nullable, required — The KPI value in its native unit
  - `unit` string, required — Unit of measurement: seconds, minutes, hours, count, or ratio

## Other responses

- `400` — Invalid parameters or unsupported KPI type
- `404` — KPI not found or organization not found

---

[API](https://skmtc.net/humansignal/apis/label-studio-api.md) · [All operations](https://skmtc.net/humansignal/apis/label-studio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/humansignal/label-studio-api/versions/1b113b8df950/schema)