Skip to main content



Groups are a tagging system that can be used to group your catalog together, enabling a variety of use cases including:

  • Including/excluding services or resources from Scorecards
  • Reporting
  • Tagging

Use cases


The simplest use case for groups is tagging. You may want to segment your catalog into different types or domains. For example:

  • Language (python, java)
  • Domain (infra, payments)
  • Type (backend/frontend, library/api)
  • Tier (tier-1, tier-2)


Once you've tagged your catalog with groups, you can use them to include/exclude services or resources from your Scorecards. For example, you may say "this Scorecard only applies to all Python services".


You can also use groups for reporting. You may want to aggregate Scorecard scores by domain or tier, for example "I want to see our Production Readiness Scorecard broken down by tier".

Catalog descriptor

Groups are defined as a list of tags.

- group-1
- another-group
- third-group

Groups must contain only alphanumeric characters, dashes (-), and colons (:). Groups may not contain whitespaces.


Since groups can be used as tags for product/domain areas and other such hierarchical data, we expose an ability to define a hierarchy of groups.

For example, you may have the following structure as a domain hierarchy paymentsorderscheckoutshopping, where any entity tagged with payments also belongs to orders, checkout, and shopping.

This hierarchy is used for:

  • Executive reporting, letting you roll up your catalog at different levels of granularity
  • Including/Excluding categories of services or from Scorecards (for example, "this Scorecard applies to all services under the shopping umbrella").
  • "My Services" and "My Resources" when using group subscriptions


Currently, you can only define hierarchies through our API.

The API accepts a list of "edges", defining relationships between groups.

curl -X PUT '' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
"parent": "cortex",
"child": "infra"
"parent": "infra",
"child": "library"

By default, this API appends any relationships to the graph you've already sent to Cortex using this API. If you want to replace the entire graph, just add a replace=true query param to the request.


  1. When should I use groups instead of custom data?
    1. 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].