--- title: Telegrafs description: Create and manage Telegraf agent configurations that collect and write data to InfluxDB Cloud. url: https://docs.influxdata.com/influxdb/cloud/api/telegrafs/ estimated_tokens: 20941 product: InfluxDB Cloud (TSM) version: cloud --- [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Create and manage Telegraf agent configurations that collect and write data to InfluxDB Cloud. GET `/api/v2/telegrafs` ### List all Telegraf configurations #### Parameters ##### Query parameters `orgID` string The organization ID the Telegraf config belongs to. ##### Header parameters `Zap-Trace-Span` string OpenTracing span context Example request [Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/telegrafs" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 A list of Telegraf configurations `configurations` object\[\] default Unexpected error `code` required string code is the machine-readable error code. Allowed: `internal error` , `not implemented` , `not found` , `conflict` , `invalid` , `unprocessable entity` , `empty value` , `unavailable` , `forbidden` , `too many requests` , `unauthorized` , `method not allowed` , `request too large` , `unsupported media type` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. POST `/api/v2/telegrafs` ### Create a Telegraf configuration #### Parameters ##### Header parameters `Zap-Trace-Span` string OpenTracing span context #### Request body required Telegraf configuration to create Content-Type: `application/json` `config` string `description` string `metadata` object `buckets` string\[\] `name` string `orgID` string `plugins` object\[\] `alias` string `config` string `description` string `name` string `type` string Example request [Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/telegrafs" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "config": "CONFIG", "description": "DESCRIPTION", "metadata": {}, "name": "NAME", "orgID": "ORGID", "plugins": [] }' ``` #### Responses 201 Telegraf configuration created default Unexpected error `code` required string code is the machine-readable error code. Allowed: `internal error` , `not implemented` , `not found` , `conflict` , `invalid` , `unprocessable entity` , `empty value` , `unavailable` , `forbidden` , `too many requests` , `unauthorized` , `method not allowed` , `request too large` , `unsupported media type` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. GET `/api/v2/telegrafs/{telegrafID}` ### Retrieve a Telegraf configuration #### Parameters ##### Path parameters `telegrafID` required string The Telegraf configuration ID. ##### Header parameters `Zap-Trace-Span` string OpenTracing span context `Accept` string Allowed values: `application/toml` , `application/json` , `application/octet-stream` Default: `application/toml` Example request [Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/telegrafs/{telegrafID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 Telegraf configuration details default Unexpected error `code` required string code is the machine-readable error code. Allowed: `internal error` , `not implemented` , `not found` , `conflict` , `invalid` , `unprocessable entity` , `empty value` , `unavailable` , `forbidden` , `too many requests` , `unauthorized` , `method not allowed` , `request too large` , `unsupported media type` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. PUT `/api/v2/telegrafs/{telegrafID}` ### Update a Telegraf configuration #### Parameters ##### Path parameters `telegrafID` required string The Telegraf config ID. ##### Header parameters `Zap-Trace-Span` string OpenTracing span context #### Request body required Telegraf configuration update to apply Content-Type: `application/json` `config` string `description` string `metadata` object `buckets` string\[\] `name` string `orgID` string `plugins` object\[\] `alias` string `config` string `description` string `name` string `type` string Example request [Ask AI about this](#) ```sh curl --request PUT \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/telegrafs/{telegrafID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "config": "CONFIG", "description": "DESCRIPTION", "metadata": {}, "name": "NAME", "orgID": "ORGID", "plugins": [] }' ``` #### Responses 200 An updated Telegraf configurations default Unexpected error `code` required string code is the machine-readable error code. Allowed: `internal error` , `not implemented` , `not found` , `conflict` , `invalid` , `unprocessable entity` , `empty value` , `unavailable` , `forbidden` , `too many requests` , `unauthorized` , `method not allowed` , `request too large` , `unsupported media type` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. DELETE `/api/v2/telegrafs/{telegrafID}` ### Delete a Telegraf configuration #### Parameters ##### Path parameters `telegrafID` required string The Telegraf configuration ID. ##### Header parameters `Zap-Trace-Span` string OpenTracing span context Example request [Ask AI about this](#) ```sh curl --request DELETE \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/telegrafs/{telegrafID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204 Delete has been accepted default Unexpected error `code` required string code is the machine-readable error code. Allowed: `internal error` , `not implemented` , `not found` , `conflict` , `invalid` , `unprocessable entity` , `empty value` , `unavailable` , `forbidden` , `too many requests` , `unauthorized` , `method not allowed` , `request too large` , `unsupported media type` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. GET `/api/v2/telegrafs/{telegrafID}/labels` ### List all labels for a Telegraf config #### Parameters ##### Path parameters `telegrafID` required string The Telegraf config ID. ##### Header parameters `Zap-Trace-Span` string OpenTracing span context Example request [Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/telegrafs/{telegrafID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 A list of all labels for a Telegraf config `labels` string `links` string default Unexpected error `code` required string code is the machine-readable error code. Allowed: `internal error` , `not implemented` , `not found` , `conflict` , `invalid` , `unprocessable entity` , `empty value` , `unavailable` , `forbidden` , `too many requests` , `unauthorized` , `method not allowed` , `request too large` , `unsupported media type` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. POST `/api/v2/telegrafs/{telegrafID}/labels` ### Add a label to a Telegraf config #### Parameters ##### Path parameters `telegrafID` required string The Telegraf config ID. ##### Header parameters `Zap-Trace-Span` string OpenTracing span context #### Request body required Label to add Content-Type: `application/json` `labelID` required string A label ID. Specifies the label to attach. Example request [Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/telegrafs/{telegrafID}/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "labelID": "LABELID" }' ``` #### Responses 201 The label added to the Telegraf config `label` string `links` string default Unexpected error `code` required string code is the machine-readable error code. Allowed: `internal error` , `not implemented` , `not found` , `conflict` , `invalid` , `unprocessable entity` , `empty value` , `unavailable` , `forbidden` , `too many requests` , `unauthorized` , `method not allowed` , `request too large` , `unsupported media type` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. DELETE `/api/v2/telegrafs/{telegrafID}/labels/{labelID}` ### Delete a label from a Telegraf config #### Parameters ##### Path parameters `telegrafID` required string The Telegraf config ID. `labelID` required string The label ID. ##### Header parameters `Zap-Trace-Span` string OpenTracing span context Example request [Ask AI about this](#) ```sh curl --request DELETE \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/telegrafs/{telegrafID}/labels/{labelID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204 Delete has been accepted 404 Telegraf config not found `code` required string code is the machine-readable error code. Allowed: `internal error` , `not implemented` , `not found` , `conflict` , `invalid` , `unprocessable entity` , `empty value` , `unavailable` , `forbidden` , `too many requests` , `unauthorized` , `method not allowed` , `request too large` , `unsupported media type` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. default Unexpected error `code` required string code is the machine-readable error code. Allowed: `internal error` , `not implemented` , `not found` , `conflict` , `invalid` , `unprocessable entity` , `empty value` , `unavailable` , `forbidden` , `too many requests` , `unauthorized` , `method not allowed` , `request too large` , `unsupported media type` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. GET `/api/v2/telegrafs/{telegrafID}/members` ### List all users with member privileges for a Telegraf config #### Parameters ##### Path parameters `telegrafID` required string The Telegraf config ID. ##### Header parameters `Zap-Trace-Span` string OpenTracing span context Example request [Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/telegrafs/{telegrafID}/members" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 A list of Telegraf config members `links` object `self` string `users` object\[\] default Unexpected error `code` required string code is the machine-readable error code. Allowed: `internal error` , `not implemented` , `not found` , `conflict` , `invalid` , `unprocessable entity` , `empty value` , `unavailable` , `forbidden` , `too many requests` , `unauthorized` , `method not allowed` , `request too large` , `unsupported media type` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. POST `/api/v2/telegrafs/{telegrafID}/members` ### Add a member to a Telegraf config #### Parameters ##### Path parameters `telegrafID` required string The Telegraf config ID. ##### Header parameters `Zap-Trace-Span` string OpenTracing span context #### Request body required User to add as member Content-Type: `application/json` `id` required string The ID of the user to add to the resource. `name` string The name of the user to add to the resource. Example request [Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/telegrafs/{telegrafID}/members" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME" }' ``` #### Responses 201 Member added to Telegraf config default Unexpected error `code` required string code is the machine-readable error code. Allowed: `internal error` , `not implemented` , `not found` , `conflict` , `invalid` , `unprocessable entity` , `empty value` , `unavailable` , `forbidden` , `too many requests` , `unauthorized` , `method not allowed` , `request too large` , `unsupported media type` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. DELETE `/api/v2/telegrafs/{telegrafID}/members/{userID}` ### Remove a member from a Telegraf config #### Parameters ##### Path parameters `userID` required string The ID of the member to remove. `telegrafID` required string The Telegraf config ID. ##### Header parameters `Zap-Trace-Span` string OpenTracing span context Example request [Ask AI about this](#) ```sh curl --request DELETE \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/telegrafs/{telegrafID}/members/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204 Member removed default Unexpected error `code` required string code is the machine-readable error code. Allowed: `internal error` , `not implemented` , `not found` , `conflict` , `invalid` , `unprocessable entity` , `empty value` , `unavailable` , `forbidden` , `too many requests` , `unauthorized` , `method not allowed` , `request too large` , `unsupported media type` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. GET `/api/v2/telegrafs/{telegrafID}/owners` ### List all owners of a Telegraf configuration #### Parameters ##### Path parameters `telegrafID` required string The Telegraf configuration ID. ##### Header parameters `Zap-Trace-Span` string OpenTracing span context Example request [Ask AI about this](#) ```sh curl --request GET \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/telegrafs/{telegrafID}/owners" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 Returns Telegraf configuration owners as a ResourceOwners list `links` object `self` string `users` object\[\] default Unexpected error `code` required string code is the machine-readable error code. Allowed: `internal error` , `not implemented` , `not found` , `conflict` , `invalid` , `unprocessable entity` , `empty value` , `unavailable` , `forbidden` , `too many requests` , `unauthorized` , `method not allowed` , `request too large` , `unsupported media type` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. POST `/api/v2/telegrafs/{telegrafID}/owners` ### Add an owner to a Telegraf configuration #### Parameters ##### Path parameters `telegrafID` required string The Telegraf configuration ID. ##### Header parameters `Zap-Trace-Span` string OpenTracing span context #### Request body required User to add as owner Content-Type: `application/json` `id` required string The ID of the user to add to the resource. `name` string The name of the user to add to the resource. Example request [Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/telegrafs/{telegrafID}/owners" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "id": "ID", "name": "NAME" }' ``` #### Responses 201 Telegraf configuration owner was added. Returns a ResourceOwner that references the User. default Unexpected error `code` required string code is the machine-readable error code. Allowed: `internal error` , `not implemented` , `not found` , `conflict` , `invalid` , `unprocessable entity` , `empty value` , `unavailable` , `forbidden` , `too many requests` , `unauthorized` , `method not allowed` , `request too large` , `unsupported media type` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging. DELETE `/api/v2/telegrafs/{telegrafID}/owners/{userID}` ### Remove an owner from a Telegraf config #### Parameters ##### Path parameters `userID` required string The ID of the owner to remove. `telegrafID` required string The Telegraf config ID. ##### Header parameters `Zap-Trace-Span` string OpenTracing span context Example request [Ask AI about this](#) ```sh curl --request DELETE \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/telegrafs/{telegrafID}/owners/{userID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204 Owner removed default Unexpected error `code` required string code is the machine-readable error code. Allowed: `internal error` , `not implemented` , `not found` , `conflict` , `invalid` , `unprocessable entity` , `empty value` , `unavailable` , `forbidden` , `too many requests` , `unauthorized` , `method not allowed` , `request too large` , `unsupported media type` `err` string Stack of errors that occurred during processing of the request. Useful for debugging. `message` string Human-readable message. `op` string Describes the logical code operation when the error occurred. Useful for debugging.