---
title: List
url: https://www.tines.com/stories/docs/api/tags/list/
updated: 2026-04-24T16:21:27+00:00
description: Retrieve a list of tags.
---

*[tines.com](https://www.tines.com/llms.txt) › [Docs](https://www.tines.com/stories/docs/llms.txt) › [Tines API](https://www.tines.com/stories/docs/api/llms.txt) › [Tags](https://www.tines.com/llm/stories/docs/api/tags.md)*

# List

*[View on tines.com](https://www.tines.com/stories/docs/api/tags/list/)*

## Description

Retrieve a list of tags.

## Request

HTTP Method: **GET**

| Query Parameter | Description                                                           |
| --------------- | --------------------------------------------------------------------- |
| team_id         | **Optional** Return tags belonging to this team.                      |
| per_page        | **Optional** The number of results returned per page. Defaults to 20. |
| page            | **Optional** The page of results to return. Defaults to 1.            |

```bash
curl -X GET \
  https://<tenant-domain>/api/v1/tags \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>'
```

## Response

A successful request will return a JSON object containing an array of tags the requesting token has access to.

### Field description

| Parameter  | Description                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------ |
| id         | Tag ID.                                                                                          |
| name       | Tag name.                                                                                        |
| color      | Tag color in hex format (for example, `#8D75E6`).                                                |
| teams      | The teams the tag belongs to. Tags created after February 2025 can only belong to a single team. |
| created_at | ISO 8601 timestamp describing when the tag was created.                                          |
| updated_at | ISO 8601 timestamp describing when the tag was last updated.                                     |

### Sample response

```json
{
  "tags": [
    {
      "id": 17,
      "name": "priority-high",
      "color": "#FF8888",
      "teams": [
        {
          "id": 100,
          "name": "Test team 1"
        },
        {
          "id": 101,
          "name": "Test team 2"
        }
      ],
      "created_at": "2026-04-10T09:15:42.128Z",
      "updated_at": "2026-04-10T09:15:42.128Z"
    },
    {
      "id": 18,
      "name": "triage",
      "color": "#4BBFFF",
      "teams": [
        {
          "id": 276,
          "name": "Test team 3"
        }
      ],
      "created_at": "2026-04-10T09:21:11.491Z",
      "updated_at": "2026-04-10T09:21:11.491Z"
    }
  ],
  "meta": {
    "current_page": "https://<tenant-domain>/api/v1/tags?per_page=20&page=1",
    "previous_page": null,
    "next_page": null,
    "next_page_number": null,
    "per_page": 20,
    "pages": 1,
    "count": 2
  }
}
```
