> ## 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 Tags

> Every tag, flat, with the group it belongs to

The same tags [List Tag Groups](/api-reference/list-tag-groups) returns nested,
as one flat list. Use this when you have a tag id and want to know what it is,
rather than walking the groups.

Each row carries `group_name` and `subject_type`, which is what tells you
whether a tag can go on an account, a person or an opportunity.

## Query Parameters

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

<ParamField query="group_id" type="string">
  Only the tags in this group.
</ParamField>

## Response Fields

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

<ResponseField name="tags[].id" type="string">
  The tag's id. This is what every tag write and the `tag` search filter take.
</ResponseField>

<ResponseField name="tags[].group_id" type="string">
  The group it lives in. A tag cannot move between groups.
</ResponseField>

<ResponseField name="tags[].group_name" type="string">
  That group's name, so a flat list still reads as "Status: Contacted".
</ResponseField>

<ResponseField name="tags[].subject_type" type="string">
  `account`, `person` or `path`, from the group.
</ResponseField>

<ResponseField name="tags[].closes" type="boolean">
  Opportunity tags only: the conversation on that path is over. This is what a
  terminal status used to be.
</ResponseField>

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "data": {
      "tags": [
        {
          "id": "7f3e1a22-0c5d-4c1e-9f8a-2b4d6e8f0a12",
          "group_id": "5a1c3f88-92d4-4b0e-8e7a-1f2b3c4d5e60",
          "group_name": "Segment",
          "subject_type": "account",
          "name": "Enterprise",
          "color": "#3B82F6",
          "position": 0,
          "closes": false
        }
      ]
    }
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": { "message": "Invalid group_id", "code": "BAD_REQUEST" }
  }
  ```
</ResponseExample>