find-labels
Read-onlyIdempotent
Retrieve Todoist labels with optional name search and pagination. Returns personal labels with full metadata and shared labels as names.
Instructions
List personal labels and shared labels. Personal labels have full metadata (id, name, color, order, isFavorite) and support pagination and name search (partial, case insensitive). Shared labels are labels used on tasks shared with you — they are returned as names only (no IDs or metadata). When searching, all matching personal labels are fetched across all pages and returned as a single result set (limit and cursor are ignored). When not searching, personal labels are returned with pagination.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | The maximum number of labels to return. | |
| cursor | No | The cursor to get the next page of labels (cursor is obtained from the previous call to this tool, with the same parameters). Ignored when searchText is provided. | |
| searchText | No | Search for a label by name (partial and case insensitive match). Supports wildcards (e.g. "work*" for prefix match). Use "\*" for a literal asterisk. If omitted, all labels are returned. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| labels | Yes | The found personal labels. | |
| hasMore | Yes | Whether there are more results available. | |
| nextCursor | No | Cursor for the next page of results. | |
| totalCount | Yes | The total number of labels in this page. | |
| sharedLabels | Yes | Names of all shared labels visible to you. These have no IDs or metadata — use their names directly when filtering tasks. | |
| appliedFilters | Yes | The filters that were applied to the search. |