---
**📚 Main Documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt)
This is an individual endpoint documentation file. For the complete API reference, see the main documentation above.
---
# (GET) Get tags
Retrieve tags from your workspace. Filter by tag ID or list all tags with pagination.
**Category:** Tags
## Endpoint

GET /api/tags

Retrieve tags by id. Supports pagination with take, skip, and sorting by tag id.

Use this endpoint to list your tags, verify tag existence, or build tag management interfaces.

**Endpoint**

```text
GET /api/tags
```

## Authentication

Requires authentication with an API key that has the tagsRead scope.

## Query Parameters

| Parameter | Type | Required | Location | Description |
|---|---|---|---|---|
| id | string (UUID) | No | query | Filter by specific tag ID. Returns a single tag if found. |
| take | number | No | query | Number of results to return (default: 50, min: 1, max: 10,000). |
| skip | number | No | query | Number of results to skip for pagination (default: 0, min: 0). |
| sort | string | No | query | Sort order by tag id: "asc" for oldest first, "desc" for newest first (default: "desc"). |

> **Warning: Request Limits**
> The `take` parameter supports values from 1 to 10,000. Requests above 10,000 are rejected.

## Status Codes

### 200

Successfully retrieved tags.

**Request**

```bash
curl -X GET "https://hoko.to/api/tags?take=50&sort=desc" \
  -H "Authorization: Bearer <API_KEY>"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/tags?take=50&sort=desc", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <API_KEY>"
  }
});
const tags = await response.json();
```

**Response**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing",
    "color": "blue"
  }
]
```

### 401

Invalid or missing API key.

**Request**

```bash
curl -X GET "https://hoko.to/api/tags" \
  -H "Authorization: Bearer invalid_key"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/tags", {
  method: "GET",
  headers: {
    "Authorization": "Bearer invalid_key"
  }
});
```

**Response**

```json
{
  "error": {
    "en": "Invalid API key",
    "ar": "مفتاح API غير صالح"
  }
}
```

### 403

API key does not have the required tagsRead scope.

**Request**

```bash
curl -X GET "https://hoko.to/api/tags" \
  -H "Authorization: Bearer <API_KEY>"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/tags", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <API_KEY>"
  }
});
```

**Response**

```json
{
  "error": {
    "en": "Missing required scopes",
    "ar": "الصلاحيات المطلوبة مفقودة"
  },
  "missingScopes": ["tagsRead"]
}
```

### 429

Rate limit exceeded. Check X-RateLimit-* headers for details.

**Request**

```bash
curl -X GET "https://hoko.to/api/tags" \
  -H "Authorization: Bearer <API_KEY>"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/tags", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <API_KEY>"
  }
});
```

**Response**

```json
{
  "error": {
    "en": "Rate limit exceeded",
    "ar": "تم تجاوز حد المعدل"
  },
  "retryAfter": 60
}
```

## Examples

**Request**

```bash
curl -X GET "https://hoko.to/api/tags?take=50&sort=desc" \
  -H "Authorization: Bearer <API_KEY>"
```

**Request**

```javascript
const response = await fetch("https://hoko.to/api/tags?take=50&sort=desc", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <API_KEY>"
  }
});
const tags = await response.json();
```

**Response**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing",
    "color": "blue"
  }
]
```

---

**Back to main documentation:** [Hoko API Documentation (llms.txt)](https://hoko.to/docs/llms.txt)