# Grouping entities
Groups are a tagging system that can be used to group a set of [entities](/ingesting-data-into-cortex/entities-overview/entities.md) together, enabling a variety of use cases including:
* Tagging
* Use groups to segment entities.
* For example, you could segment by tiers (`tier-0` to indicate high priority), type (backend, frontend, library, API), or language (Python, Java).
* Filtering throughout Cortex
* Use groups to include or exclude certain entities from [Scorecards](/standardize/scorecards.md), [catalogs](/ingesting-data-into-cortex/catalogs.md), [CQL reports](/standardize/cql/cql-reports.md), and more.
* For example, you may want a Scorecard to only apply to Python services or a catalog that only shows tier-0 services.
* Reporting
* You could aggregate Scorecard scores by a specific group, such as a tier.
* For example, viewing a Production Readiness Scorecard broken down by tier.
While viewing an entity, its groups are listed in the upper right side of the page:
Click the group name to view a list of all other entities that are tagged with this group.
## How to define and apply groups
You can create new groups in an entity's YAML, directly in the Cortex UI, or via the API. When creating a new group, it is applied to the entity where you are creating the group.
Note the following considerations:
* If a group has been set in the entity descriptor YAML, an API call will **not** overwrite the existing value.
* Groups created via the API will not appear in the entity descriptor YAML.
* Groups created via the API cannot be removed via the Cortex UI.
{% tabs %}
{% tab title="Cortex UI" %}
To create a group in the UI:
1. Navigate to the entity that you want to apply a group to.
* Click the magnifying glass icon at the bottom of the main nav, or click **Catalogs > All entities** and search for the entity from that page.
2. In the upper right corner of the entity page, click **Configure entity**.
3. Click into the **Groups** field.
* To apply an existing group, type to search then click on the group.
* To create a new group, type the group name into the field, then click the group name in the dropdown. The group will be created and applied to the entity.
4. At the bottom of the page, click **Save**.
{% endtab %}
{% tab title="Entity descriptor" %}
Groups are defined as a list of tags.
```yaml
x-cortex-groups:
- tier0
- language:kotlin
```
Groups may not contain whitespace characters.
{% endtab %}
{% tab title="API" %}
You can use the API to add groups to an entity. See the [API documentation for groups here](/api/readme/groups.md).
{% endtab %}
{% endtabs %}
## Troubleshooting and FAQ
#### **When should I use groups instead of** [**custom data**](/ingesting-data-into-cortex/entities-overview/entities/custom-data.md)**?**
To determine whether or not to use groups or custom data, consider whether your use case would be considered "tagging" with a definite enum of values (`backend` vs `frontend`), or more freeform metadata `availability-zones: [east, west]`.
#### **What is the difference between `x-cortex-service-groups` and `x-cortex-groups`?**
There is no difference between these. `x-cortex-service-groups` has been deprecated in favor of `x-cortex-groups`, but the change is backward-compatible.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/groups.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.