---
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: 3043
product: InfluxDB Cloud (TSM)
version: cloud
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb/cloud/api/labels/
---

[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

200Success. The response body contains a list of labels.

`labels`string

`links`string

500Internal server error.
The server encountered an unexpected situation.

`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.

defaultNon 2XX error response from server.

`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/labels`

### Create a label

#### Request bodyrequired

The label to create.

Content-Type:`application/json`

`name`requiredstring

`orgID`requiredstring

`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

201Success. The label was created.

`label`string

`links`string

500Internal server error.
The server encountered an unexpected situation.

`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.

defaultNon 2XX error response from server.

`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/labels/{labelID}`

### Retrieve a label

#### Parameters

##### Path parameters

`labelID`requiredstring

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

200Success. The response body contains the label.

`label`string

`links`string

500Internal server error.
The server encountered an unexpected situation.

`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.

defaultNon 2XX error response from server.

`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.

PATCH`/api/v2/labels/{labelID}`

### Update a label

#### Parameters

##### Path parameters

`labelID`requiredstring

The ID of the label to update.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

#### Request bodyrequired

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

200Success. 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`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.

500Internal server error.
The server encountered an unexpected situation.

`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.

defaultNon 2XX error response from server.

`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/labels/{labelID}`

### Delete a label

#### Parameters

##### Path parameters

`labelID`requiredstring

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

204Success. 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`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.

500Internal server error.
The server encountered an unexpected situation.

`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.

defaultNon 2XX error response from server.

`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.