--- 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: 4605 product: InfluxDB Cloud (TSM) version: cloud publisher: InfluxData canonical: https://docs.influxdata.com/influxdb/cloud/api/telegrafs/ --- [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 200A list of Telegraf configurations `configurations`object[] defaultUnexpected error `code`requiredstring 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 bodyrequired 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 201Telegraf configuration created defaultUnexpected error `code`requiredstring 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`requiredstring 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 200Telegraf configuration details defaultUnexpected error `code`requiredstring 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`requiredstring The Telegraf config ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired 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 200An updated Telegraf configurations defaultUnexpected error `code`requiredstring 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`requiredstring 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 204Delete has been accepted defaultUnexpected error `code`requiredstring 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`requiredstring 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 200A list of all labels for a Telegraf config `labels`string `links`string defaultUnexpected error `code`requiredstring 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`requiredstring The Telegraf config ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired Label to add Content-Type:`application/json` `labelID`requiredstring 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 201The label added to the Telegraf config `label`string `links`string defaultUnexpected error `code`requiredstring 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`requiredstring The Telegraf config ID. `labelID`requiredstring 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 204Delete has been accepted 404Telegraf config not found `code`requiredstring 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. defaultUnexpected error `code`requiredstring 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`requiredstring 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 200A list of Telegraf config members `links`object `self`string \ `users`object[] defaultUnexpected error `code`requiredstring 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`requiredstring The Telegraf config ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired User to add as member Content-Type:`application/json` `id`requiredstring 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 201Member added to Telegraf config defaultUnexpected error `code`requiredstring 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`requiredstring The ID of the member to remove. `telegrafID`requiredstring 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 204Member removed defaultUnexpected error `code`requiredstring 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`requiredstring 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 200Returns Telegraf configuration owners as a ResourceOwners list `links`object `self`string \ `users`object[] defaultUnexpected error `code`requiredstring 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`requiredstring The Telegraf configuration ID. ##### Header parameters `Zap-Trace-Span`string OpenTracing span context #### Request bodyrequired User to add as owner Content-Type:`application/json` `id`requiredstring 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 201Telegraf configuration owner was added. Returns a ResourceOwner that references the User. defaultUnexpected error `code`requiredstring 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`requiredstring The ID of the owner to remove. `telegrafID`requiredstring 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 204Owner removed defaultUnexpected error `code`requiredstring 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.