---
title: Buckets
description: Create and manage named storage locations (buckets) in InfluxDB OSS v2, each with a configurable retention period.
url: https://docs.influxdata.com/influxdb/v2/api/buckets/
estimated_tokens: 16101
product: InfluxDB OSS v2
version: v2
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb/v2/api/buckets/
---

[Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml)

Create and manage named storage locations (buckets) in InfluxDB OSS v2, each with a configurable retention period.

GET`/api/v2/buckets`

### List buckets

Lists [buckets](/influxdb/v2/reference/glossary/#bucket).

InfluxDB retrieves buckets owned by the[organization](/influxdb/v2/reference/glossary/#organization)associated with the authorization
([API token](/influxdb/v2/reference/glossary/#token)).
To limit which buckets are returned, pass query parameters in your request.
If no query parameters are passed, InfluxDB returns all buckets up to the
default `limit`.

#### InfluxDB OSS v2

* If you use an *[operator token](/influxdb/v2/security/tokens/#operator-token)*to authenticate your request, InfluxDB retrieves resources for *all
  organizations* in the instance.
  To retrieve resources for only a specific organization, use the`org` parameter or the `orgID` parameter to specify the organization.

#### Required permissions

|                                   Action                                    |Permission required|
|-----------------------------------------------------------------------------|-------------------|
|                           Retrieve *user buckets*                           |  `read-buckets`   |
|Retrieve [*system buckets*](/influxdb/v2/reference/internals/system-buckets/)|    `read-orgs`    |

#### Related Guides

* [Manage buckets](/influxdb/v2/organizations/buckets/)

#### Parameters

##### Query parameters

`offset`integer

The offset for pagination.
The number of records to skip.

For more information about pagination parameters, see [Pagination](/influxdb/v2/api/#tag/Pagination).

`limit`integer

Limits the number of records returned. Default is `20`.

Default:`20`

`after`string

A resource ID to seek from.
Returns records created after the specified record;
results don’t include the specified record.

Use `after` instead of the `offset` parameter.
For more information about pagination parameters, see [Pagination](/influxdb/v2/api/#tag/Pagination).

`org`string

An organization name.

#### InfluxDB Cloud

* Doesn’t use the `org` parameter or `orgID` parameter.
* Lists buckets for the organization associated with the authorization (API token).

#### InfluxDB OSS v2

* Lists buckets for the specified organization.

`orgID`string

An organization ID.

#### InfluxDB Cloud

* Doesn’t use the `org` parameter or `orgID` parameter.
* Lists buckets for the organization associated with the authorization (API token).

#### InfluxDB OSS v2

* Requires either the `org` parameter or `orgID` parameter.
* Lists buckets for the specified organization.

`name`string

A bucket name.
Only returns buckets with the specified name.

`id`string

A bucket ID.
Only returns the bucket with the specified ID.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "http://localhost:8086/api/v2/buckets" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success.
The response body contains a list of `buckets`.

`buckets`object[]

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

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.

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

### Create a bucket

Creates a [bucket](/influxdb/v2/reference/glossary/#bucket)and returns the bucket resource.
The default data[retention period](/influxdb/v2/reference/glossary/#retention-period)is 30 days.

#### InfluxDB OSS v2

* A single InfluxDB OSS instance supports active writes or queries for
  approximately 20 buckets across all organizations at a given time.
  Reading or writing to more than 20 buckets at a time can adversely affect
  performance.

#### Limitations

* InfluxDB Cloud Free Plan allows users to create up to two buckets.
  Exceeding the bucket quota will result in an HTTP `403` status code.
  For additional information regarding InfluxDB Cloud offerings, see[InfluxDB Cloud Pricing](https://www.influxdata.com/influxdb-cloud-pricing/).

#### Related Guides

* [Create a bucket](/influxdb/v2/organizations/buckets/create-bucket/)
* [Create bucket CLI reference](/influxdb/v2/reference/cli/influx/bucket/create)

#### Parameters

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

#### Request bodyrequired

The bucket to create.

Content-Type:`application/json`

`description`string

A description of the bucket.

`name`requiredstring

The bucket name.

`orgID`requiredstring

The organization ID.
Specifies the organization that owns the bucket.

`retentionRules`string

`rp`string

The retention policy for the bucket.
For InfluxDB 1.x, specifies the duration of time that each data point
in the retention policy persists.

If you need compatibility with InfluxDB 1.x, specify a value for the `rp` property;
otherwise, see the `retentionRules` property.

[Retention policy](/influxdb/v2/reference/glossary/#retention-policy-rp)is an InfluxDB 1.x concept.
The InfluxDB 2.x and Cloud equivalent is[retention period](/influxdb/v2/reference/glossary/#retention-period).
The InfluxDB `/api/v2` API uses `RetentionRules` to configure the retention period.

Default:`0`

`schemaType`string

The schema Type. Default is `implicit`.

#### InfluxDB Cloud v2

* Use `explicit` to enforce column names, tags, fields, and data types for
  your data.

#### InfluxDB OSS v2

* Doesn’t support `explicit` bucket schemas.

Default:`implicit`

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "http://localhost:8086/api/v2/buckets" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "description": "DESCRIPTION",
  "name": "NAME",
  "orgID": "ORGID",
  "retentionRules": [],
  "rp": "0",
  "schemaType": "implicit"
}'
```

#### Responses

201Success.
The bucket is created.

`createdAt`string \<date-time\>

`description`string

`id`string

`labels`string

`links`object

Example:`{"labels":"/api/v2/buckets/1/labels","members":"/api/v2/buckets/1/members","org":"/api/v2/orgs/2","owners":"/api/v2/buckets/1/owners","self":"/api/v2/buckets/1","write":"/api/v2/write?org=2\u0026bucket=1"}`

`labels`string

The URL to retrieve labels for this bucket.

`members`string

The URL to retrieve members that can read this bucket.

`org`string

The URL to retrieve parent organization for this bucket.

`owners`string

The URL to retrieve owners that can read and write to this bucket.

`self`string

The URL for this bucket.

`write`string

The URL to write line protocol to this bucket.

`name`requiredstring

`orgID`string

`retentionRules`requiredstring

`rp`string

`schemaType`string

Default:`implicit`

`type`string

Allowed:`user`, `system`

Default:`user`

`updatedAt`string \<date-time\>

400Bad request.

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

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.

403Forbidden.
The bucket quota is exceeded.

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

422Unprocessable Entity.
The request body failed validation.

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

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/buckets/{bucketID}`

### Retrieve a bucket

Retrieves a bucket.

Use this endpoint to retrieve information for a specific bucket.

#### Parameters

##### Path parameters

`bucketID`requiredstring

The ID of the bucket to retrieve.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "http://localhost:8086/api/v2/buckets/{bucketID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success.
The response body contains the bucket information.

`createdAt`string \<date-time\>

`description`string

`id`string

`labels`string

`links`object

Example:`{"labels":"/api/v2/buckets/1/labels","members":"/api/v2/buckets/1/members","org":"/api/v2/orgs/2","owners":"/api/v2/buckets/1/owners","self":"/api/v2/buckets/1","write":"/api/v2/write?org=2\u0026bucket=1"}`

`labels`string

The URL to retrieve labels for this bucket.

`members`string

The URL to retrieve members that can read this bucket.

`org`string

The URL to retrieve parent organization for this bucket.

`owners`string

The URL to retrieve owners that can read and write to this bucket.

`self`string

The URL for this bucket.

`write`string

The URL to write line protocol to this bucket.

`name`requiredstring

`orgID`string

`retentionRules`requiredstring

`rp`string

`schemaType`string

Default:`implicit`

`type`string

Allowed:`user`, `system`

Default:`user`

`updatedAt`string \<date-time\>

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.

404Not found.
Bucket 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.

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.

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.

PATCH`/api/v2/buckets/{bucketID}`

### Update a bucket

Updates a bucket.

Use this endpoint to update properties
(`name`, `description`, and `retentionRules`) of a bucket.

#### InfluxDB Cloud

* Requires the `retentionRules` property in the request body. If you don’t
  provide `retentionRules`, InfluxDB responds with an HTTP `403` status code.

#### InfluxDB OSS v2

* Doesn’t require `retentionRules`.

#### Related Guides

* [Update a bucket](/influxdb/v2/organizations/buckets/update-bucket/)

#### Parameters

##### Path parameters

`bucketID`requiredstring

The bucket ID.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

#### Request bodyrequired

The bucket update to apply.

Content-Type:`application/json`

`description`string

A description of the bucket.

`name`string

The name of the bucket.

`retentionRules`string

Example request[Ask AI about this](#)

```sh
curl --request PATCH \
  "http://localhost:8086/api/v2/buckets/{bucketID}" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "description": "DESCRIPTION",
  "name": "NAME",
  "retentionRules": []
}'
```

#### Responses

200An updated bucket

`createdAt`string \<date-time\>

`description`string

`id`string

`labels`string

`links`object

Example:`{"labels":"/api/v2/buckets/1/labels","members":"/api/v2/buckets/1/members","org":"/api/v2/orgs/2","owners":"/api/v2/buckets/1/owners","self":"/api/v2/buckets/1","write":"/api/v2/write?org=2\u0026bucket=1"}`

`labels`string

The URL to retrieve labels for this bucket.

`members`string

The URL to retrieve members that can read this bucket.

`org`string

The URL to retrieve parent organization for this bucket.

`owners`string

The URL to retrieve owners that can read and write to this bucket.

`self`string

The URL for this bucket.

`write`string

The URL to write line protocol to this bucket.

`name`requiredstring

`orgID`string

`retentionRules`requiredstring

`rp`string

`schemaType`string

Default:`implicit`

`type`string

Allowed:`user`, `system`

Default:`user`

`updatedAt`string \<date-time\>

400Bad Request.

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

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.

403Forbidden.

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

404Not found.
Bucket 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.

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.

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/buckets/{bucketID}`

### Delete a bucket

Deletes a bucket and all associated records.

#### InfluxDB Cloud

* Does the following when you send a delete request:

  1. Validates the request and queues the delete.
  2. Returns an HTTP `204` status code if queued; *error* otherwise.
  3. Handles the delete asynchronously.

#### InfluxDB OSS v2

* Validates the request, handles the delete synchronously,
  and then responds with success or failure.

#### Limitations

* Only one bucket can be deleted per request.

#### Related Guides

* [Delete a bucket](/influxdb/v2/organizations/buckets/delete-bucket/#delete-a-bucket-in-the-influxdb-ui)

#### Parameters

##### Path parameters

`bucketID`requiredstring

Bucket ID.
The ID of the bucket to delete.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "http://localhost:8086/api/v2/buckets/{bucketID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

204

Success.

#### InfluxDB Cloud

* The bucket is queued for deletion.

#### InfluxDB OSS v2

* The bucket is deleted.

400Bad Request.

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

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.

404Not found.
Bucket 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.

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.

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

### List all labels for a bucket

Lists all labels for a bucket.

Labels are objects that contain `labelID`, `name`, `description`, and `color`key-value pairs. They may be used for grouping and filtering InfluxDB
resources.
Labels are also capable of grouping across different resources–for example,
you can apply a label named `air_sensor` to a bucket and a task to quickly
organize resources.

#### Related guides

* Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels.
* [Manage labels in the InfluxDB UI](/influxdb/v2/visualize-data/labels/)

#### Parameters

##### Path parameters

`bucketID`requiredstring

The ID of the bucket to retrieve labels for.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "http://localhost:8086/api/v2/buckets/{bucketID}/labels" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success.
The response body contains a list of all labels for the bucket.

`labels`string

`links`string

400

Bad request.
The response body contains detail about the error.

#### InfluxDB OSS v2

* Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter.

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

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.

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

### Add a label to a bucket

Adds a label to a bucket and returns the new label information.

Labels are objects that contain `labelID`, `name`, `description`, and `color`key-value pairs. They may be used for grouping and filtering across one or
more kinds of **resources**–for example, you can apply a label named`air_sensor` to a bucket and a task to quickly organize resources.

#### Limitations

* Before adding a label to a bucket, you must create the label if you
  haven’t already. To create a label with the InfluxDB API, send a `POST`request to the [`/api/v2/labels` endpoint](#operation/PostLabels)).

#### Related guides

* Use the [`/api/v2/labels` InfluxDB API endpoint](#tag/Labels) to retrieve and manage labels.
* [Manage labels in the InfluxDB UI](/influxdb/v2/visualize-data/labels/)

#### Parameters

##### Path parameters

`bucketID`requiredstring

Bucket ID.
The ID of the bucket to label.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

#### Request bodyrequired

An object that contains a *`labelID`* to add to the bucket.

Content-Type:`application/json`

`labelID`requiredstring

A label ID.
Specifies the label to attach.

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "http://localhost:8086/api/v2/buckets/{bucketID}/labels" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "labelID": "LABELID"
}'
```

#### Responses

201Success.
The response body contains the label information.

`label`string

`links`string

400

Bad request.
The response body contains detail about the error.

#### InfluxDB OSS v2

* Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter.

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

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.

422Unprocessable entity.
Label already exists on the resource.

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

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

### Delete a label from a bucket

#### Parameters

##### Path parameters

`bucketID`requiredstring

The bucket ID.

`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 \
  "http://localhost:8086/api/v2/buckets/{bucketID}/labels/{labelID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

204Delete has been accepted

404Bucket 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/buckets/{bucketID}/members`

### List all users with member privileges for a bucket

Lists all users for a bucket.

InfluxDB [users](/influxdb/v2/reference/glossary/#user) have
permission to access InfluxDB.

[Members](/influxdb/v2/reference/glossary/#member) are users in
an organization with access to the specified resource.

Use this endpoint to retrieve all users with access to a bucket.

#### Related guides

* [Manage users](/influxdb/v2/users/)
* [Manage members](/influxdb/v2/organizations/members/)

#### Parameters

##### Path parameters

`bucketID`requiredstring

The ID of the bucket to retrieve users for.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "http://localhost:8086/api/v2/buckets/{bucketID}/members" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success.
The response body contains a list of all users for the bucket.

`links`object

`self`string \<uri\>

`users`object[]

400

Bad request.
The response body contains detail about the error.

#### InfluxDB OSS v2

* Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter.

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

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.

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/buckets/{bucketID}/members`

### Add a member to a bucket

Add a user to a bucket and return the new user information.

InfluxDB [users](/influxdb/v2/reference/glossary/#user) have
permission to access InfluxDB.

[Members](/influxdb/v2/reference/glossary/#member) are users in
an organization.

Use this endpoint to give a user member privileges to a bucket.

#### Related guides

* [Manage users](/influxdb/v2/users/)
* [Manage members](/influxdb/v2/organizations/members/)

#### Parameters

##### Path parameters

`bucketID`requiredstring

The ID of the bucket to retrieve users for.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

#### Request bodyrequired

A user to add as a member to the bucket.

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 \
  "http://localhost:8086/api/v2/buckets/{bucketID}/members" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "id": "ID",
  "name": "NAME"
}'
```

#### Responses

201Success.
The response body contains the user information.

400

Bad request.
The response body contains detail about the error.

#### InfluxDB OSS v2

* Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter.

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

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.

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/buckets/{bucketID}/members/{userID}`

### Remove a member from a bucket

Removes a member from a bucket.

Use this endpoint to remove a user’s member privileges from a bucket. This
removes the user’s `read` and `write` permissions for the bucket.

#### Related guides

* [Manage users](/influxdb/v2/users/)
* [Manage members](/influxdb/v2/organizations/members/)

#### Parameters

##### Path parameters

`userID`requiredstring

The ID of the user to remove.

`bucketID`requiredstring

The ID of the bucket to remove a user from.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "http://localhost:8086/api/v2/buckets/{bucketID}/members/{userID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

204Success.
The user is no longer a member of the bucket.

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.

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/buckets/{bucketID}/owners`

### List all owners of a bucket

Lists all [owners](/influxdb/v2/reference/glossary/#owner)of a bucket.

Bucket owners have permission to delete buckets and remove user and member
permissions from the bucket.

#### InfluxDB Cloud

* Doesn’t use `owner` and `member` roles.
  Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.

#### Limitations

* Owner permissions are separate from API token permissions.
* Owner permissions are used in the context of the InfluxDB UI.

#### Required permissions

* `read-orgs INFLUX_ORG_ID`

*`INFLUX_ORG_ID`* is the ID of the organization that you want to retrieve a
list of owners for.

#### Related endpoints

* [Authorizations](#tag/Authorizations-(API-tokens))

#### Related guides

* [Manage users](/influxdb/v2/users/)

#### Parameters

##### Path parameters

`bucketID`requiredstring

The ID of the bucket to retrieve owners for.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "http://localhost:8086/api/v2/buckets/{bucketID}/owners" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success.
The response body contains a list of all owners for the bucket.

`links`object

`self`string \<uri\>

`users`object[]

400

Bad request.
The response body contains detail about the error.

#### InfluxDB OSS v2

* Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter.

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

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.

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/buckets/{bucketID}/owners`

### Add an owner to a bucket

Adds an owner to a bucket and returns the [owners](/influxdb/v2/reference/glossary/#owner)with role and user detail.

Use this endpoint to create a *resource owner* for the bucket.
Bucket owners have permission to delete buckets and remove user and member
permissions from the bucket.

#### InfluxDB Cloud

* Doesn’t use `owner` and `member` roles.
  Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.

#### Limitations

* Owner permissions are separate from API token permissions.
* Owner permissions are used in the context of the InfluxDB UI.

#### Required permissions

* `write-orgs INFLUX_ORG_ID`*`INFLUX_ORG_ID`* is the ID of the organization that you want to add
  an owner for.

#### Related endpoints

* [Authorizations](#tag/Authorizations-(API-tokens))

#### Related guides

* [Manage users](/influxdb/v2/users/)

#### Parameters

##### Path parameters

`bucketID`requiredstring

The ID of the bucket to add an owner for.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

#### Request bodyrequired

A user to add as an owner for the bucket.

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 \
  "http://localhost:8086/api/v2/buckets/{bucketID}/owners" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "id": "ID",
  "name": "NAME"
}'
```

#### Responses

201Created.
The bucket `owner` role is assigned to the user.
The response body contains the resource owner with
role and user detail.

400

Bad request.
The response body contains detail about the error.

#### InfluxDB OSS v2

* Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter.

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

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.

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/buckets/{bucketID}/owners/{userID}`

### Remove an owner from a bucket

Removes an owner from a bucket.

Use this endpoint to remove a user’s `owner` role for a bucket.

#### InfluxDB Cloud

* Doesn’t use `owner` and `member` roles.
  Use [`/api/v2/authorizations`](#tag/Authorizations-(API-tokens)) to assign user permissions.

#### Limitations

* Owner permissions are separate from API token permissions.
* Owner permissions are used in the context of the InfluxDB UI.

#### Required permissions

* `write-orgs INFLUX_ORG_ID`

*`INFLUX_ORG_ID`* is the ID of the organization that you want to remove an owner
from.

#### Related endpoints

* [Authorizations](#tag/Authorizations-(API-tokens))

#### Related guides

* [Manage users](/influxdb/v2/users/)

#### Parameters

##### Path parameters

`userID`requiredstring

The ID of the owner to remove.

`bucketID`requiredstring

The ID of the bucket to remove an owner from.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "http://localhost:8086/api/v2/buckets/{bucketID}/owners/{userID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

204Success.
The user is no longer an owner of the bucket.

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.

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/sources/{sourceID}/buckets`

### Get buckets in a source

#### Parameters

##### Path parameters

`sourceID`requiredstring

The source ID.

##### Query parameters

`org`string

The name of the organization.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "http://localhost:8086/api/v2/sources/{sourceID}/buckets" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200A source

`buckets`object[]

`links`string

404Source 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.

#### Related

* [Manage buckets](/influxdb/v2/organizations/buckets/)
| Action | Permission required |
| --- | --- |
| Action | Permission required |
| Retrieve  user buckets | read-buckets |
| Retrieve  system buckets | read-orgs |