> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clustr-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Tag Groups

> Every tag group in your workspace, with its tags

A tag group is a named set of tags for one kind of record. Every label on a
record is a tag in one of these groups, so this is the lookup that makes every
other tag call usable: assignments and filters are by **id**, and the ids come
from here.

See [Tags](/tags) for the model.

## The three subjects

| `subject_type` | Labels                                    | Addressed by                    |
| -------------- | ----------------------------------------- | ------------------------------- |
| `account`      | Companies                                 | the company UUID (`company_id`) |
| `person`       | People, connectors included               | the person's LinkedIn id        |
| `path`         | Opportunities, a connector and a prospect | the pair of LinkedIn ids        |

<Note>
  **A status is a tag.** What used to be an opportunity status is a tag in a
  `path` group, usually still named Status. That group is `single`, so setting
  one of its tags replaces the previous one. A tag with `closes: true` is what
  used to be a terminal status: the conversation on that path is over.
</Note>

## Query Parameters

<ParamField query="subject_type" type="string">
  `account`, `person` or `path`. Omit for all three.
</ParamField>

<ParamField query="with_counts" type="string">
  Set to `true` to add how many records carry each tag, as
  `tags_with_counts[].subject_count`. Off by default, because the count is an
  aggregate across three assignment tables and a picker does not show it. It is
  what tells you whether a tag is safe to delete.
</ParamField>

## Response Fields

<ResponseField name="groups" type="array">
  The groups, in display order.
</ResponseField>

<ResponseField name="groups[].id" type="string">
  The group's id. Pass it as `group_id` when creating a tag, or as `group_id` on
  a tag write to scope a replace to this group.
</ResponseField>

<ResponseField name="groups[].subject_type" type="string">
  `account`, `person` or `path`. Fixed when the group is created.
</ResponseField>

<ResponseField name="groups[].selection" type="string">
  `single` holds at most one of the group's tags per record, so adding another
  replaces it. `multi` holds any number.
</ResponseField>

<ResponseField name="groups[].is_system" type="boolean">
  `true` for a group Clustr seeds and depends on. It can be renamed, but
  `DELETE` on it returns 422.
</ResponseField>

<ResponseField name="groups[].tags" type="array">
  The group's tags, in display order: `id`, `name`, `color`, `position` and
  `closes`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.clustr-ai.com/api/public/tag-groups?subject_type=path" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  groups = requests.get(
      "https://api.clustr-ai.com/api/public/tag-groups",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={"subject_type": "path"},
  ).json()["data"]["groups"]

  status = next(g for g in groups if g["name"] == "Status")
  by_name = {t["name"]: t["id"] for t in status["tags"]}
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://api.clustr-ai.com/api/public/tag-groups?subject_type=account", {
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "groups": [
        {
          "id": "2b7c9d10-4e5f-4a61-9c22-8d3f1a7b0e44",
          "subject_type": "path",
          "name": "Status",
          "selection": "single",
          "position": 0,
          "is_system": false,
          "tags": [
            {
              "id": "8f652e61-edfa-4a8c-8763-cc4902dd386b",
              "group_id": "2b7c9d10-4e5f-4a61-9c22-8d3f1a7b0e44",
              "name": "Contacted",
              "color": "#3B82F6",
              "position": 0,
              "closes": false
            },
            {
              "id": "7e4cc70e-2644-4b1e-9006-57222533dde4",
              "group_id": "2b7c9d10-4e5f-4a61-9c22-8d3f1a7b0e44",
              "name": "Not interested",
              "color": "#EF4444",
              "position": 1,
              "closes": true
            }
          ]
        }
      ]
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": { "message": "subject_type must be account, person or path", "code": "BAD_REQUEST" }
  }
  ```
</ResponseExample>