---
title: "List tag groups"
method: GET
path: "/api/v1/tag-groups"
tags: ["Tag Groups"]
---

# List tag groups

`GET /api/v1/tag-groups`

## Request

- Base URL: `https://app.scanopy.net`
- URL: `https://app.scanopy.net/api/v1/tag-groups`
- Auth: one of:
  - API key in header `Authorization`
  - API key in cookie `session_id`

Returns every tag group in your organization: the system groups (Application, Status) first,
then the groups your organization named, by name.

## Query parameters

- `system` boolean[], nullable
- `ordered` boolean[], nullable
- `entity_types` EntityDiscriminants[], nullable
- `include_every_entity_type` boolean, nullable
- `tag_ids` string[], nullable
- `search` string, nullable
- `group_by` 'created_at' | 'name' | 'updated_at' | 'group_type' | 'ordered': Fields the tag groups list can be ordered and grouped by.
- `order_by` 'created_at' | 'name' | 'updated_at' | 'group_type' | 'ordered': Fields the tag groups list can be ordered and grouped by.
- `order_direction` 'asc' | 'desc': Direction for ORDER BY clauses.
- `limit` integer, nullable
- `offset` integer, nullable

## Response `200`

List of tag groups

- object: Response type for paginated list endpoints (pagination is always present in meta)
  - `data` object[], required: The page of results. Empty when nothing matched the query.
    - `description` string, nullable, required: What the group is for.
    - `entity_types` EntityDiscriminants[], nullable, required: The entity types this group's tags can be applied to. `null` allows every taggable type the group type admits: Status leaves out types that carry a status of their own. Fixed for Visibility, which applies to hosts.
    - `group_type` 'Application' | 'Status' | 'Visibility' | 'Custom', required: What kind of tag group this is. `Application`, `Status` and `Visibility` are system groups: every organization has exactly one of each, and they can't be renamed, deleted or recreated. Application tags drive the application view. Status tags track where an asset is on its way from planned to decommissioned, on entities that have no status of their own. A host holding a Visibility tag is left out of topology. `Custom` groups are named by the organization.
    - `name` string, required: The group's name. A system group's name is fixed.
    - `ordered` boolean, required: Whether the group's tags have an order the organization sets. An unordered group lists its tags by name. Fixed for system groups: statuses are ordered, applications are not.
    - `organization_id` string, uuid, required: The organization that owns this record.
    - `scope_computed` boolean, required: Whether `entity_types` is computed from entity metadata (Status, Visibility) rather than set by the organization. A computed scope is read-only and never stored.
    - `created_at` string, date-time, required: When this record was first created.
    - `id` string, uuid, required: Server-assigned unique identifier.
    - `updated_at` string, date-time, required: When this record was last modified.
  - `error` string, nullable: Human-readable failure message. Omitted on success.
  - `meta` PaginatedApiMeta, required: API metadata for paginated list responses (pagination is always present)
    - `api_version` integer, required: API version (integer, increments on breaking changes)
    - `pagination` PaginationMeta, required: Pagination metadata returned with paginated responses.
      - `group_counts` GroupCount[], nullable: Size of every group, in the same order the rows are grouped, when the request specified a `group_by`. Lets a paginated client show a group's true size instead of the slice of it that happens to be on this page. Absent when the list isn't grouped.
        - `count` integer, required: How many rows fall in this group in total, not just on this page.
        - `value` string, nullable: The group's value, rendered as text. `null` for rows whose group key is NULL (the "ungrouped" bucket).
      - `has_more` boolean, required: Whether there are more items after this page
      - `limit` integer, required: Maximum items per page (as requested)
      - `offset` integer, required: Number of items skipped
      - `total_count` integer, required: Total number of items matching the filter (ignoring pagination)
    - `server_version` string, required: Server version (semver)
  - `success` boolean, required: `true` when the request succeeded. `false` responses carry `error` instead of `data`.

## Changes

- **2026-10-26** `c9d9d46d1ae8`: 1 info
  - api operation id `get_all_tag_groups` removed and replaced with `list_tag_groups`
- **2026-10-23** `9dda1a8b8ed1`: 1 info
  - the response required property `data/items/allOf[#/components/schemas/TagGroupBase]/group_type` became read-only for the status `200`
- **2026-10-23** `c9f50be8bc26`: 11 info
  - added the new optional `query` request parameter `entity_types`
  - added the new optional `query` request parameter `group_by`
  - added the new optional `query` request parameter `include_every_entity_type`
  - added the new optional `query` request parameter `limit`
  - …7 more
- **2026-10-11** `e5d9c243ed3c`: 1 warning, 2 info
  - added the new `Visibility` enum value to the `data/items/allOf[#/components/schemas/TagGroupBase]/group_type` response property for the response status `200`
  - added the required property `data/items/allOf[#/components/schemas/TagGroupBase]/description` to the response with the `200` status
  - added the required property `data/items/allOf[#/components/schemas/TagGroupBase]/scope_computed` to the response with the `200` status
- **2026-10-11** `8de5826e9ffc`: 1 info
  - added the required property `data/items/allOf[#/components/schemas/TagGroupBase]/ordered` to the response with the `200` status

[Operation history](https://skmtc.dev/scanopy/apis/scanopy-api/changes/api/v1/tag-groups/get.md)

---

[API](https://skmtc.dev/scanopy/apis/scanopy-api.md) - [All operations](https://skmtc.dev/scanopy/apis/scanopy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/scanopy/apis/scanopy-api/revisions/966ba786bdb5?raw)