--- title: Labels description: Create and manage labels for organizing InfluxDB Cloud resources such as dashboards, tasks, and buckets. url: https://docs.influxdata.com/influxdb/cloud/api/labels/ estimated_tokens: 12254 product: InfluxDB Cloud (TSM) version: cloud --- [Download InfluxDB Cloud (TSM) API Spec](/openapi/influxdb-cloud-v2-api.yml) Create and manage labels for organizing InfluxDB Cloud resources such as dashboards, tasks, and buckets. GET `/api/v2/labels` ### List all labels #### Parameters ##### Query parameters `orgID` string The organization 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/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 Success. The response body contains a list of labels. `labels` string `links` string 500 Internal server error. The server encountered an unexpected situation. `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 Non 2XX error response from server. `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/labels` ### Create a label #### Request body required The label to create. Content-Type: `application/json` `name` required string `orgID` required string `properties` object Key-value pairs associated with this label. To remove a property, send an update with an empty value (`""`) for the key. Example: `{"color":"ffb3b3","description":"this is a description"}` Example request [Ask AI about this](#) ```sh curl --request POST \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/labels" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "name": "NAME", "orgID": "ORGID", "properties": { "color": "ffb3b3", "description": "this is a description" } }' ``` #### Responses 201 Success. The label was created. `label` string `links` string 500 Internal server error. The server encountered an unexpected situation. `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 Non 2XX error response from server. `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/labels/{labelID}` ### Retrieve a label #### Parameters ##### Path parameters `labelID` required string The ID of the label to update. ##### 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/labels/{labelID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 200 Success. The response body contains the label. `label` string `links` string 500 Internal server error. The server encountered an unexpected situation. `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 Non 2XX error response from server. `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. PATCH `/api/v2/labels/{labelID}` ### Update a label #### Parameters ##### Path parameters `labelID` required string The ID of the label to update. ##### Header parameters `Zap-Trace-Span` string OpenTracing span context #### Request body required A label update. Content-Type: `application/json` `name` string `properties` object Example: `{"color":"ffb3b3","description":"this is a description"}` Example request [Ask AI about this](#) ```sh curl --request PATCH \ "https://us-east-1-1.aws.cloud2.influxdata.com/api/v2/labels/{labelID}" \ --header "Authorization: Bearer INFLUX_TOKEN" \ --header "Content-Type: application/json" \ --data-raw '{ "name": "NAME", "properties": { "color": "ffb3b3", "description": "this is a description" } }' ``` #### Responses 200 Success. The response body contains the updated label. `label` string `links` string 401 Unauthorized. The error may indicate one of the following: - The `Authorization: Token` header is missing or malformed. - The API token value is missing from the header. - The token doesn’t have sufficient permissions to write to this organization and bucket. `code` string The HTTP status code description. Default is `unauthorized`. Allowed: `unauthorized` `message` string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: - `"organization name \"my-org\" not found"` - `"organization not found"`: indicates you passed an ID that did not match an organization. `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. 500 Internal server error. The server encountered an unexpected situation. `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 Non 2XX error response from server. `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/labels/{labelID}` ### Delete a label #### Parameters ##### Path parameters `labelID` required string The ID of the label to delete. ##### 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/labels/{labelID}" \ --header "Authorization: Bearer INFLUX_TOKEN" ``` #### Responses 204 Success. The delete was accepted. 401 Unauthorized. The error may indicate one of the following: - The `Authorization: Token` header is missing or malformed. - The API token value is missing from the header. - The token doesn’t have sufficient permissions to write to this organization and bucket. `code` string The HTTP status code description. Default is `unauthorized`. Allowed: `unauthorized` `message` string A human-readable message that may contain detail about the error. 404 Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example: - `"organization name \"my-org\" not found"` - `"organization not found"`: indicates you passed an ID that did not match an organization. `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. 500 Internal server error. The server encountered an unexpected situation. `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 Non 2XX error response from server. `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.