---
title: Use configuration groups
description: Apply a Telegraf configuration group to your agents with a single URL, substitute values across member configurations, and keep agents up to date as the group changes.
url: https://docs.influxdata.com/telegraf/controller/config-groups/use/
estimated_tokens: 704
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/controller/config-groups/use/
date: '2026-08-25T08:20:28-06:00'
lastmod: '2026-08-25T08:20:28-06:00'
---

Apply a configuration group by pointing your agents to the group’s TOML URL,
the same way you [apply an individual configuration](/telegraf/controller/configs/use/).

## Apply a configuration group to an agent

When starting a Telegraf agent, use a `--config` flag with the
Telegraf Controller configuration group TOML API URL:

```bash
telegraf \
  --config "http://localhost:8888/api/config-groups/xxxxxx/toml"
```

The URL accepts the group ID or a[group alias](/telegraf/controller/config-groups/aliases/). If the group has
an alias, you can use the shorter alias-based URL instead:

```bash
telegraf \
  --config "http://localhost:8888/c/my-group-alias"
```

To have Telegraf Controller build the command for you, click**Use this Config Group** on the group detail page.

If Telegraf Controller requires authentication on the **Config Groups**API, provide an API token with **read** permissions the same way as for
individual configurations. For details, see[Use API tokens](/telegraf/controller/tokens/use/).

## Substitute values in group members

[Value substitution](/telegraf/controller/configs/substitute-values/) is
carried by the member configurations; a group renders whatever substitution
references its members contain:

* **Parameters**: query parameters on the group URL apply to all members.
  If any member has a required parameter without a value, the request
  returns an error listing the missing parameter names.
* **Constants**: resolved server-side across all members. Undefined
  constants cause an error listing the missing names.
* **Environment variables and secrets**: pass through unchanged and are
  resolved by the Telegraf agent, as with individual configurations.

For example, to set a parameter used by any member of the group:

```bash
telegraf \
  --config "http://localhost:8888/api/config-groups/xxxxxx/toml?agent_id=web-01"
```

## Auto-update agents

Include `--config-url-watch-interval` to have agents periodically check the
group URL for changes:

```bash
telegraf \
  --config "http://localhost:8888/api/config-groups/xxxxxx/toml" \
  --config-url-watch-interval 1h
```

The group’s last-modified time reflects the group itself, its member
configurations, and any constants they reference. Adding, removing, or
reordering members, editing a member configuration, or updating a
referenced constant all cause watching agents to reload the merged
configuration on their next check.

## View agents using a group

On the group detail page, select the **Agents** tab to see the agents
reporting with this group.

#### Related

* [Use Telegraf configurations](/telegraf/controller/configs/use/)
* [Substitute values in configurations](/telegraf/controller/configs/substitute-values/)
* [Manage configuration group aliases](/telegraf/controller/config-groups/aliases/)