---
title: "List labels"
method: GET
path: "/labels"
tags: ["Labels"]
---

# List labels

`GET /labels`

## Request

- Base URL: `https://api.speakai.co/v1`
- URL: `https://api.speakai.co/v1/labels`
- Auth: API key in header `x-speakai-key` and API key in header `x-access-token`

Returns your company's labels as a tree: groups and ungrouped labels at the top level, each group carrying the labels inside it. Items are ordered by `sortOrder`, then by name. Groups go one level deep.

No labels permission is needed: anyone on the team can read the list.

#### Filtering

- `status` picks active labels (the default), archived ones, or both.
- `search` matches names, ignoring case. A group is listed when its own name matches or when any of its labels match; it then carries only the matching labels.

#### Usage counts

`usageCount` counts labelled passages only on media you can open, so it never reveals anything about files in folders you cannot access. Owners and members with **Access all** on folders see company-wide counts.

## Query parameters

- `status` 'active' | 'archived' | 'all'
- `search` string

## Response `200`

Success

- object
  - `status` 'success': `success` on every 2xx response.
  - `data` object: The result.
    - `labels` object[]: Top-level groups and ungrouped labels.
      - `labelId` string: Id of the label or group.
      - `isGroup` boolean: `true` for a group. A group holds labels and cannot be applied to a transcript.
      - `name` string: Name.
      - `description` string: Description. Left out when none was set.
      - `color` string: `#rrggbb` in lower case. Groups have none.
      - `parentId` string, nullable: `labelId` of the group this label sits in, or `null` at the top level.
      - `source` 'user' | 'speak': `speak` for labels added from a Speak label set, `user` for everything else.
      - `isActive` boolean: `false` once archived.
      - `mergedInto` string: `labelId` this label was merged into. Present only on merged labels.
      - `sortOrder` integer: Position among its siblings.
      - `userId` string: Id of the person who created it.
      - `createdAt` string, date-time: When it was created.
      - `updatedAt` string, date-time: When it last changed.
      - `usageCount` integer: How many labelled passages use it, counted only on media you can open. For a group, the sum over its listed labels.
      - `labels` object[]: Groups only: the labels in the group that match the filter, with the same fields.
        - `labelId` string: Id of the label or group.
        - `isGroup` boolean: `true` for a group. A group holds labels and cannot be applied to a transcript.
        - `name` string: Name.
        - `description` string: Description. Left out when none was set.
        - `color` string: `#rrggbb` in lower case. Groups have none.
        - `parentId` string, nullable: `labelId` of the group this label sits in, or `null` at the top level.
        - `source` 'user' | 'speak': `speak` for labels added from a Speak label set, `user` for everything else.
        - `isActive` boolean: `false` once archived.
        - `mergedInto` string: `labelId` this label was merged into. Present only on merged labels.
        - `sortOrder` integer: Position among its siblings.
        - `userId` string: Id of the person who created it.
        - `createdAt` string, date-time: When it was created.
        - `updatedAt` string, date-time: When it last changed.
        - `usageCount` integer: How many labelled passages use it, counted only on media you can open. For a group, the sum over its listed labels.

## Other responses

- `400`: A query value failed validation

---

[API](https://skmtc.dev/speakai/apis/speak-ai-api.md) · [All operations](https://skmtc.dev/speakai/apis/speak-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/speakai/apis/speak-ai-api/revisions/52d777e6d46e?raw)