---
updatedAt: 2026-01-28T15:08:04.000Z
---

Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further.

# Labels

Retrieve task labels for a task board. Labels help categorize and filter tasks.

## Endpoint

| Method | Endpoint                                  | Description     |
| :----- | :---------------------------------------- | :-------------- |
| GET    | /tasks/v1/taskboards/{taskBoardId}/labels | Get task labels |

***

## Path Parameters

| Parameter   | Type   | Required | Description   |
| :---------- | :----- | :------- | :------------ |
| taskBoardId | string | Yes      | Task board ID |

## Query Parameters

| Parameter | Type    | Required | Default | Description              |
| :-------- | :------ | :------- | :------ | :----------------------- |
| title     | string  | No       | -       | Filter by label name     |
| limit     | integer | No       | 10      | Results per page (1-100) |
| offset    | integer | No       | 0       | Pagination offset        |

***

## Example Request

```bash
curl --request GET \
  --url 'https://api.connecteam.com/tasks/v1/taskboards/12345/labels?limit=100' \
  --header 'X-API-KEY: YOUR_API_KEY'
```

***

## Response

```json
{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "labels": [
      {
        "id": "label-abc123",
        "name": "Urgent",
        "color": "#FF0000"
      },
      {
        "id": "label-def456",
        "name": "Maintenance",
        "color": "#00FF00"
      },
      {
        "id": "label-ghi789",
        "name": "Training",
        "color": "#0000FF"
      }
    ]
  },
  "paging": {
    "offset": 3
  }
}
```

***

## Response Fields

| Field | Type   | Description             |
| :---- | :----- | :---------------------- |
| id    | string | Unique label identifier |
| name  | string | Display name            |
| color | string | Hex color code          |

***

## Using Labels

### Get All Labels for a Board

```javascript
async function getAllLabels(taskBoardId) {
  const labels = [];
  let offset = 0;
  const limit = 100;

  while (true) {
    const response = await fetch(
      `https://api.connecteam.com/tasks/v1/taskboards/${taskBoardId}/labels?limit=${limit}&offset=${offset}`,
      { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
    );
    const data = await response.json();
    
    labels.push(...data.data.labels);
    
    if (data.data.labels.length < limit) break;
    offset = data.paging.offset;
  }

  return labels;
}
```

### Build Label Mapping

```javascript
const labels = await getAllLabels(12345);

// Map label names to IDs
const labelMap = {};
labels.forEach(label => {
  labelMap[label.name] = label.id;
});

// Use when creating tasks
await createTask({
  title: 'Urgent maintenance required',
  userIds: [9170357],
  status: 'published',
  labelIds: [labelMap['Urgent'], labelMap['Maintenance']]
});
```

### Filter Tasks by Label

```javascript
// Get tasks with specific labels
const urgentTasks = await fetch(
  `https://api.connecteam.com/tasks/v1/taskboards/12345/tasks?labelIds=${labelMap['Urgent']}`,
  { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
);
```

***

[API Reference](https://developer.connecteam.com/reference/)