---
title: Enterprise
description: 'Endpoints available only in InfluxDB 3 Enterprise. Operations carrying this tag also set x-enterprise-only: true for programmatic detection.'
url: https://docs.influxdata.com/influxdb3/enterprise/api/enterprise/
estimated_tokens: 20837
product: InfluxDB 3 Enterprise
version: enterprise
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb3/enterprise/api/enterprise/
---

[Download InfluxDB 3 Enterprise API Spec](/openapi/influxdb3-enterprise-openapi.yml)

Endpoints available only in InfluxDB 3 Enterprise. Operations carrying this tag also set `x-enterprise-only: true` for programmatic detection.

POST`/api/v3/authorize`

### 

#### Request bodyrequired

Content-Type:`application/json`

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/authorize" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json"
```

#### Responses

200Success

POST`/api/v3/authorize/refresh`

### 

#### Request bodyrequired

Content-Type:`application/json`

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/authorize/refresh" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json"
```

#### Responses

200Success

POST`/api/v3/authorize/reset-password`

### 

#### Request bodyrequired

Content-Type:`application/json`

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/authorize/reset-password" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json"
```

#### Responses

200Success

GET`/api/v3/configure/query_concurrency_limit`

### Get the query concurrency limit

Returns the current runtime limit on the maximum number of queries that can run concurrently. When the limit is set to the maximum allowed value, `maxConcurrentQueries` is omitted from the response.

This endpoint is only available in InfluxDB 3 Enterprise.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/configure/query_concurrency_limit" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Returns the current query concurrency limit.

`max_concurrent_queries`integer

The maximum number of queries that can run concurrently. Omitted when the limit is set to the maximum allowed value.

Example request body

```json
{
  "max_concurrent_queries": 32
}
```

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

PUT`/api/v3/configure/query_concurrency_limit`

### Set the query concurrency limit

Sets the runtime limit on the maximum number of queries that can run concurrently. Omit `max_concurrent_queries` (or set it to `null`) to restore the limit configured at server startup.

Values below 16 are rejected unless `force=true` is set in the query string. A value of `0` is invalid, and values above the maximum allowed limit are rejected.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Parameters

##### Query parameters

`force`boolean

Set to `true` to allow setting `max_concurrent_queries` to a value below the minimum of 16.

#### Request bodyrequired

Content-Type:`application/json`

`max_concurrent_queries`integer

The maximum number of queries that can run concurrently. Set to `null` (or omit) to restore the limit configured at server startup. Must be a positive integer; values below 16 require `force=true`.

Example request body

```json
{
  "max_concurrent_queries": 32
}
```

Example request[Ask AI about this](#)

```sh
curl --request PUT \
  "https://localhost:8181/api/v3/configure/query_concurrency_limit" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"max_concurrent_queries":32}'
```

#### Responses

204No content. The query concurrency limit was updated.

400

Request failed. Possible reasons:

* Invalid database name
* Malformed request body
* Invalid timestamp precision

`data`object

`error`string

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

DELETE`/api/v3/configure/query_concurrency_limit`

### Reset the query concurrency limit

Resets the runtime query concurrency limit to the value configured at server startup.

This endpoint is only available in InfluxDB 3 Enterprise.

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "https://localhost:8181/api/v3/configure/query_concurrency_limit" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

204No content. The query concurrency limit was reset.

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

PUT`/api/v3/configure/table`

### Update a table

Updates a table’s retention period.

This endpoint doesn’t add columns. Other properties in the request body,
such as `tags` or `fields`, are ignored, and the request still returns`200`. To add columns, use `PATCH /api/v3/configure/table`.

#### Request bodyrequired

Content-Type:`application/json`

`db`requiredstring

The name of the database containing the table.

`retention_period`string

The retention period for the table. Specifies how long data in this table should be retained.
Use duration format (for example, “1d”, “1h”, “30m”, “7d”).

Example:`"30d"`

`table`requiredstring

The name of the table to update.

Example request[Ask AI about this](#)

```sh
curl --request PUT \
  "https://localhost:8181/api/v3/configure/table" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "db": "DB",
  "retention_period": "30d",
  "table": "TABLE"
}'
```

#### Responses

200Success. The table has been updated.

400Bad request.

401Unauthorized access.

`data`object

`error`string

404Table not found.

POST`/api/v3/configure/user`

### 

#### Request bodyrequired

Content-Type:`application/json`

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/configure/user" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json"
```

#### Responses

200Success

GET`/api/v3/enterprise/backup`

### List backups

Lists all full backups.

Requires an admin (operator) token. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node; otherwise the endpoint returns `503 Service Unavailable`.

This endpoint is only available in InfluxDB 3 Enterprise.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/enterprise/backup" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Returns the list of backups.

`backups`requiredobject[]

All full backups.

`completed_at`string \<date-time\>

The completion timestamp. Omitted when the backup is not complete.

`created_at`requiredstring \<date-time\>

The creation timestamp.

`name`requiredstring

The backup name.

`status`requiredstring

The status of a backup or restore.

Allowed:`in_progress`, `completed`, `failed`

`total_files`requiredinteger \<int64\>

The number of files in the backup.

`total_size_bytes`requiredinteger \<int64\>

The total backup size in bytes.

`type`requiredstring

The backup type.

Allowed:`full`, `incremental`

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

500Internal server error. Listing backups failed.

`data`object

`error`string

503Service unavailable. The backup engine is not present on this node (not a compactor node).

`data`object

`error`string

POST`/api/v3/enterprise/backup`

### Start a backup

Registers and asynchronously starts a full backup. Returns immediately with the resolved backup name and an in-progress acknowledgement.

Backups run asynchronously. Poll [List backups](#operation/GetEnterpriseBackup) or [Get a backup](#operation/GetEnterpriseBackupByName) to track progress.

Requires an admin (operator) token. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node; otherwise the endpoint returns `503 Service Unavailable`.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Request bodyrequired

Content-Type:`application/json`

`force`boolean

Overwrite an existing backup of the same name.

`name`string

The backup name. Defaults to a generated name when omitted.

`type`requiredstring

The backup type. Only `full` backups are supported.

Allowed:`full`

Example request body

```json
{
  "force": false,
  "name": "nightly-backup",
  "type": "full"
}
```

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/enterprise/backup" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"force":false,"name":"nightly-backup","type":"full"}'
```

#### Responses

202Accepted. The backup has started.

`backup_name`requiredstring

The resolved backup name.

`status`requiredstring

The status of a newly started backup. Always `in_progress`.

Allowed:`in_progress`

Example request body

```json
{
  "backup_name": "nightly-backup",
  "status": "in_progress"
}
```

400

Request failed. Possible reasons:

* Invalid database name
* Malformed request body
* Invalid timestamp precision

`data`object

`error`string

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

409Conflict. A backup with that name already exists and `force` is `false`, or a duplicate backup job is already in flight.

`data`object

`error`string

503Service unavailable. The backup engine is not present on this node (not a compactor node).

`data`object

`error`string

DELETE`/api/v3/enterprise/backup`

### Cancel a running backup

Cancels an in-progress backup job by name.

Requires an admin (operator) token or admin user. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node; otherwise the endpoint returns `503 Service Unavailable`.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Request bodyrequired

Content-Type:`application/json`

`name`requiredstring

The name of the backup job to cancel.

Example request body

```json
{
  "name": "nightly-backup"
}
```

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "https://localhost:8181/api/v3/enterprise/backup" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"name":"nightly-backup"}'
```

#### Responses

200Success. The cancellation has been accepted.

`backup_name`requiredstring

The cancelled backup name.

Example request body

```json
{
  "backup_name": "nightly-backup"
}
```

400

Request failed. Possible reasons:

* Invalid database name
* Malformed request body
* Invalid timestamp precision

`data`object

`error`string

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

404Not found. No backup is running with that name.

`data`object

`error`string

503Service unavailable. The backup engine is not present on this node (not a compactor node).

`data`object

`error`string

GET`/api/v3/enterprise/backup/{name}`

### Get a backup

Returns a single backup’s manifest.

Requires an admin (operator) token or admin user. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node; otherwise the endpoint returns `503 Service Unavailable`.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Parameters

##### Path parameters

`name`requiredstring

The backup name. URL-encoded names are decoded by the server.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/enterprise/backup/{name}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Returns the backup manifest.

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

404Not found. No backup exists with that name.

`data`object

`error`string

503Service unavailable. The backup engine is not present on this node (not a compactor node).

`data`object

`error`string

DELETE`/api/v3/enterprise/backup/{name}`

### Delete a backup

Deletes a backup by name.

Requires an admin (operator) token or admin user. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node; otherwise the endpoint returns `503 Service Unavailable`.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Parameters

##### Path parameters

`name`requiredstring

The backup name. URL-encoded names are decoded by the server.

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "https://localhost:8181/api/v3/enterprise/backup/{name}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. The backup has been deleted.

`backup_name`requiredstring

The deleted backup name.

`type`requiredstring

The backup type.

Allowed:`full`, `incremental`

Example request body

```json
{
  "backup_name": "nightly-backup",
  "type": "full"
}
```

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

404Not found. No backup exists with that name.

`data`object

`error`string

409Conflict. The backup is in progress and cannot be deleted, or the backup chain is in a conflicting state.

`data`object

`error`string

503Service unavailable. The backup engine is not present on this node (not a compactor node).

`data`object

`error`string

POST`/api/v3/enterprise/configure/file_index`

### Create a file index

Creates a file index for a database or table.

A file index improves query performance by indexing data files based on specified columns, enabling the query engine to skip irrelevant files during query execution.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Request bodyrequired

Content-Type:`application/json`

`columns`requiredstring[]

The columns to use for the file index.

`db`requiredstring

The database name.

`table`string

The table name. If omitted, the file index applies to the database.

Example request body

```json
{
  "columns": [
    "tag1",
    "tag2"
  ],
  "db": "mydb",
  "table": "mytable"
}
```

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/enterprise/configure/file_index" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"columns":["tag1","tag2"],"db":"mydb","table":"mytable"}'
```

#### Responses

200Success. The file index has been created.

400Bad request.

401Unauthorized access.

`data`object

`error`string

404Database or table not found.

DELETE`/api/v3/enterprise/configure/file_index`

### Delete a file index

Deletes a file index from a database or table.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Request bodyrequired

Content-Type:`application/json`

`db`requiredstring

The database name.

`table`string

The table name. If omitted, deletes the database-level file index.

Example request body

```json
{
  "db": "mydb",
  "table": "mytable"
}
```

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "https://localhost:8181/api/v3/enterprise/configure/file_index" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"db":"mydb","table":"mytable"}'
```

#### Responses

200Success. The file index has been deleted.

400Bad request.

401Unauthorized access.

`data`object

`error`string

404Database, table, or file index not found.

POST`/api/v3/enterprise/configure/node/remove`

### Permanently remove a stopped node

Permanently removes a node that has already been marked as stopped, deleting its data from object storage once the compactor finishes reassigning its work.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Related

* [influxdb3 remove node](/influxdb3/enterprise/reference/cli/influxdb3/remove/node/)
* [influxdb3 stop node](/influxdb3/enterprise/reference/cli/influxdb3/stop/node/)

#### Request bodyrequired

Content-Type:`application/json`

`force_finalize`boolean

Force-finalize a node stuck in the `Stopping` state (for example, after a crash that never acknowledged the stop). This can delete unsnapshotted WAL data for that node — only use it when the node’s process is confirmed gone and you accept the data-loss risk.

`node_id`requiredstring

The ID of the node to remove.

Example request body

```json
{
  "node_id": "node-1"
}
```

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/enterprise/configure/node/remove" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"node_id":"node-1"}'
```

#### Responses

200Success. The node has been removed.

400

Request failed. Possible reasons:

* Invalid database name
* Malformed request body
* Invalid timestamp precision

`data`object

`error`string

401Unauthorized access.

`data`object

`error`string

404Node not found.

409The node is not in a state that allows removal (for example, still running).

POST`/api/v3/enterprise/configure/node/stop`

### Mark a node as stopped

Marks a node as stopped in the catalog, freeing up the licensed cores it was using for other nodes.

Use this endpoint after you have already stopped the physical instance (for example, using `kill` or stopping the container). This endpoint does not shut down the running process — you must stop the instance first.

When the node is marked as stopped:

1. Licensed cores from the stopped node are freed for reuse
2. Other nodes in the cluster see the update after their catalog sync interval

This endpoint is only available in InfluxDB 3 Enterprise.

#### Related

* [influxdb3 stop node](/influxdb3/enterprise/reference/cli/influxdb3/stop/node/)

#### Request bodyrequired

Content-Type:`application/json`

`node_id`requiredstring

The ID of the node to mark as stopped.

Example request body

```json
{
  "node_id": "node-1"
}
```

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/enterprise/configure/node/stop" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"node_id":"node-1"}'
```

#### Responses

200Success. The node has been marked as stopped.

401Unauthorized access.

`data`object

`error`string

404Node not found.

GET`/api/v3/enterprise/configure/query_groups`Not operational

### List distributed query groups (not yet operational)

Reserved for the distributed query group feature.

>
>
> **Not yet operational**: Request and response fields aren’t finalized, and InfluxDB 3 Enterprise doesn’t yet use query group definitions to affect query routing, data placement, or replication.
>
>

This endpoint is only available in InfluxDB 3 Enterprise.

#### Related

* [influxdb3 show query\_groups](/influxdb3/enterprise/reference/cli/influxdb3/show/query_groups/)

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/enterprise/configure/query_groups" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Not documented. This endpoint is not yet operational; response fields aren’t finalized.

401Unauthorized access.

`data`object

`error`string

POST`/api/v3/enterprise/configure/query_groups`Not operational

### Create a distributed query group (not yet operational)

Reserved for the distributed query group feature.

>
>
> **Not yet operational**: Request and response fields aren’t finalized, and InfluxDB 3 Enterprise doesn’t yet use query group definitions to affect query routing, data placement, or replication.
>
>

This endpoint is only available in InfluxDB 3 Enterprise.

#### Related

* [influxdb3 create query\_group](/influxdb3/enterprise/reference/cli/influxdb3/create/query_group/)

#### Request bodyrequired

Content-Type:`application/json`

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/enterprise/configure/query_groups" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json"
```

#### Responses

201Created. Not documented. This endpoint is not yet operational; response fields aren’t finalized.

400

Request failed. Possible reasons:

* Invalid database name
* Malformed request body
* Invalid timestamp precision

`data`object

`error`string

401Unauthorized access.

`data`object

`error`string

GET`/api/v3/enterprise/configure/query_groups/{id}`Not operational

### Retrieve a distributed query group (not yet operational)

Reserved for the distributed query group feature.

>
>
> **Not yet operational**: Request and response fields aren’t finalized, and InfluxDB 3 Enterprise doesn’t yet use query group definitions to affect query routing, data placement, or replication.
>
>

This endpoint is only available in InfluxDB 3 Enterprise.

#### Parameters

##### Path parameters

`id`requiredinteger

The ID of the query group.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/enterprise/configure/query_groups/{id}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Not documented. This endpoint is not yet operational; response fields aren’t finalized.

401Unauthorized access.

`data`object

`error`string

404Query group not found.

PUT`/api/v3/enterprise/configure/query_groups/{id}`Not operational

### Replace a distributed query group (not yet operational)

Reserved for the distributed query group feature.

>
>
> **Not yet operational**: Request and response fields aren’t finalized, and InfluxDB 3 Enterprise doesn’t yet use query group definitions to affect query routing, data placement, or replication.
>
>

This endpoint is only available in InfluxDB 3 Enterprise.

#### Related

* [influxdb3 update query\_group](/influxdb3/enterprise/reference/cli/influxdb3/update/query_group/)

#### Parameters

##### Path parameters

`id`requiredinteger

The ID of the query group.

#### Request bodyrequired

Content-Type:`application/json`

Example request[Ask AI about this](#)

```sh
curl --request PUT \
  "https://localhost:8181/api/v3/enterprise/configure/query_groups/{id}" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json"
```

#### Responses

200Success. Not documented. This endpoint is not yet operational; response fields aren’t finalized.

400

Request failed. Possible reasons:

* Invalid database name
* Malformed request body
* Invalid timestamp precision

`data`object

`error`string

401Unauthorized access.

`data`object

`error`string

404Query group not found.

PATCH`/api/v3/enterprise/configure/query_groups/{id}`Not operational

### Update a distributed query group (not yet operational)

Reserved for the distributed query group feature.

>
>
> **Not yet operational**: Request and response fields aren’t finalized, and InfluxDB 3 Enterprise doesn’t yet use query group definitions to affect query routing, data placement, or replication.
>
>

This endpoint is only available in InfluxDB 3 Enterprise.

#### Related

* [influxdb3 update query\_group](/influxdb3/enterprise/reference/cli/influxdb3/update/query_group/)

#### Parameters

##### Path parameters

`id`requiredinteger

The ID of the query group.

#### Request bodyrequired

Content-Type:`application/json`

Example request[Ask AI about this](#)

```sh
curl --request PATCH \
  "https://localhost:8181/api/v3/enterprise/configure/query_groups/{id}" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json"
```

#### Responses

200Success. Not documented. This endpoint is not yet operational; response fields aren’t finalized.

400

Request failed. Possible reasons:

* Invalid database name
* Malformed request body
* Invalid timestamp precision

`data`object

`error`string

401Unauthorized access.

`data`object

`error`string

404Query group not found.

DELETE`/api/v3/enterprise/configure/query_groups/{id}`Not operational

### Delete a distributed query group (not yet operational)

Reserved for the distributed query group feature.

>
>
> **Not yet operational**: Request and response fields aren’t finalized, and InfluxDB 3 Enterprise doesn’t yet use query group definitions to affect query routing, data placement, or replication.
>
>

This endpoint is only available in InfluxDB 3 Enterprise.

#### Related

* [influxdb3 delete query\_group](/influxdb3/enterprise/reference/cli/influxdb3/delete/query_group/)

#### Parameters

##### Path parameters

`id`requiredinteger

The ID of the query group.

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "https://localhost:8181/api/v3/enterprise/configure/query_groups/{id}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. The query group has been deleted.

401Unauthorized access.

`data`object

`error`string

404Query group not found.

POST`/api/v3/enterprise/configure/table/retention_period`

### Set table retention period

Sets or updates the retention period for a specific table.

Use this endpoint to control how long data in a table is retained independently of the database-level retention period.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Related

* [influxdb3 update table](/influxdb3/enterprise/reference/cli/influxdb3/update/table/)

#### Parameters

##### Query parameters

`db`requiredstring

The database name.

`table`requiredstring

The table name.

`duration`requiredstring

The retention period as a human-readable duration (for example, “30d”, “24h”, “1y”).

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/enterprise/configure/table/retention_period?db=DB&table=TABLE&duration=DURATION" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

204Success. The table retention period has been set.

400Bad request. Invalid duration format.

401Unauthorized access.

`data`object

`error`string

404Database or table not found.

DELETE`/api/v3/enterprise/configure/table/retention_period`

### Clear table retention period

Removes the retention period from a specific table, reverting to the database-level retention period (or infinite retention if no database-level retention is set).

This endpoint is only available in InfluxDB 3 Enterprise.

#### Related

* [influxdb3 update table](/influxdb3/enterprise/reference/cli/influxdb3/update/table/)

#### Parameters

##### Query parameters

`db`requiredstring

The database name.

`table`requiredstring

The table name.

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "https://localhost:8181/api/v3/enterprise/configure/table/retention_period?db=DB&table=TABLE" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

204Success. The table retention period has been cleared.

401Unauthorized access.

`data`object

`error`string

404Database or table not found.

POST`/api/v3/enterprise/configure/token`

### Create a resource token

Creates a resource (fine-grained permissions) token.
A resource token is a token that has access to specific resources in the system.

This endpoint is only available in InfluxDB 3 Enterprise.
InfluxDB 3 Cloud supports a narrower set of database-scoped read and write tokens instead of resource
tokens—see [Manage tokens in InfluxDB 3 Cloud](/influxdb3/cloud/admin/tokens/).
InfluxDB 3 Core doesn’t support resource tokens.

#### Request bodyrequired

Content-Type:`application/json`

`expiry_secs`integer

Optional expiration time in seconds.

`permissions`requiredobject[]

List of permissions to grant to the token.

`actions`requiredstring[]

List of actions to grant.

`resource_names`requiredstring[]

List of resource names. Use “\*” for all resources.

`resource_type`requiredstring

The type of resource.

Allowed:`system`, `db`

`token_name`requiredstring

The name for the resource token.

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/enterprise/configure/token" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "expiry_secs": 0,
  "permissions": [
    {
      "actions": [],
      "resource_names": [],
      "resource_type": "system"
    }
  ],
  "token_name": "TOKEN_NAME"
}'
```

#### Responses

201Success. The resource token has been created.
The response body contains the token string and metadata.

`expiry_secs`integer

The expiration time in seconds.

`permissions`object[]

`actions`string[]

`resource_names`string[]

List of resource names. Use “\*” for all resources.

`resource_type`string

Allowed:`system`, `db`

`token_name`string

Example request body

```json
{
  "expiry_secs": 300000,
  "permissions": [
    {
      "actions": [
        "read"
      ],
      "resource_names": [
        "*"
      ],
      "resource_type": "system"
    }
  ],
  "token_name": "All system information"
}
```

401Unauthorized access.

`data`object

`error`string

GET`/api/v3/enterprise/import`

### List bulk import statuses

Lists the status of bulk import jobs, for both uploads and object-store pulls.

Requires a token with the `describe` action on at least one database, or an admin token. The list includes only jobs for databases the token can describe. A token that can’t describe any database gets `403`.

Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag).

This endpoint is only available in InfluxDB 3 Enterprise.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/enterprise/import" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Returns the list of bulk import statuses.

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

500Internal server error. Object store or read failure.

`data`object

`error`string

POST`/api/v3/enterprise/import`

### Import Parquet data

Imports Parquet data into an existing table. Send the data one of two ways:

* **Upload** (`multipart/form-data`): send one Parquet file in the request.
* **Object-store pull** (`application/json`): name a `source` prefix, and the server imports every Parquet
  file under it. The source is either a prefix in the cluster’s own object store or an `s3://bucket/prefix`URL. The server reads another bucket with its own object-store credentials; the request carries none, so
  those credentials must be able to read the bucket. A server whose own object store isn’t S3 can’t read
  another bucket and returns `400`.

The request returns after the import is staged. The compactor node imports the data asynchronously. A job
moves through `queued`, `imported`, and `compacted`; rows become queryable once the job is `compacted`.
Use [List bulk import statuses](#operation/GetEnterpriseImport) to follow it.

#### Column types

For generic Parquet files, a column that isn’t in `column_metadata` is imported as a field, typed from its
Parquet type. This applies even when the target table already declares the column as a tag, so map every
string tag column (for example, `{"column_mapping": {"host": "tag"}}`). Otherwise the import fails with`invalid column type for column 'host', expected iox::column_type::tag, got iox::column_type::field::string`.
A string column with no mapping can also fail with `400` `Unable to infer data type for column`.

#### Explicit schema databases

In a database created with `schema_mode: explicit`, every column in the file must already be declared on the
table. Otherwise the import is rejected and no job is created. Declare columns with`PATCH /api/v3/configure/table`.

#### Permissions

Requires a token with the `write` action on the target database (for example, `db:DATABASE_NAME:write`), or an
admin token. For a token without that permission, including when the database doesn’t exist, the request
returns `403`.

Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag); the compactor node runs the
bulk import scheduler that completes the import.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Request bodyrequired

Content-Type:`application/json`

`column_metadata`object

Column metadata for a bulk import. Maps column names to InfluxDB column types to declare tag, field, and time columns.

Example:`{"column_mapping":{"room":"tag","temp":"f64","time":"time"}}`

`column_mapping`requiredobject

A map of column name to InfluxDB column type. The JSON key accepts the aliases `column_mapping`, `schema`, and `column_metadata`.

`database`requiredstring

The target database name. The database must already exist.

`source`requiredstring

Where to read Parquet files: a prefix in the cluster’s own object store (for example, `staging/exports/`), or an `s3://bucket/prefix` URL. Every Parquet file under the prefix is imported.

`table`requiredstring

The target table name. The table must already exist.

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/enterprise/import" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "column_metadata": {
    "column_mapping": {
      "room": "tag",
      "temp": "f64",
      "time": "time"
    }
  },
  "database": "DATABASE",
  "source": "SOURCE",
  "table": "TABLE"
}'
```

#### Responses

200Success. The upload has been staged for import.

`column_metadata`object

Column metadata for a bulk import. Maps column names to InfluxDB column types to declare tag, field, and time columns.

Example:`{"column_mapping":{"room":"tag","temp":"f64","time":"time"}}`

`column_mapping`requiredobject

A map of column name to InfluxDB column type. The JSON key accepts the aliases `column_mapping`, `schema`, and `column_metadata`.

`completed_at`integer \<int64\>

When the import completed, in nanoseconds since the Unix epoch.

`created_at`requiredinteger \<int64\>

When the uploaded file was ready for import, in nanoseconds since the Unix epoch.

`db_id`requiredinteger

The ID of the database resolved from the supplied name.

`filename`requiredstring

The filename of the uploaded Parquet data file.

`iox_parquet`requiredboolean

Whether the file was written by IOx (richer embedded metadata).

`last_message`string

The last error message if the job has errored.

`last_updated_at`integer \<int64\>

When this info last changed, in nanoseconds since the Unix epoch.

`max_timestamp_ns`requiredinteger \<int64\>

The maximum timestamp in the file (nanoseconds), from the time column’s Parquet statistics. `0` when the file has no statistics the server can read; the imported data isn’t affected.

`min_timestamp_ns`requiredinteger \<int64\>

The minimum timestamp in the file (nanoseconds), from the time column’s Parquet statistics. `0` when the file has no statistics the server can read; the imported data isn’t affected.

`row_count`requiredinteger \<int64\>

The row count from Parquet metadata.

`size_bytes`requiredinteger \<int64\>

The total size of the uploaded Parquet file in bytes.

`started_at`integer \<int64\>

When the import began, in nanoseconds since the Unix epoch.

`status`requiredstring

The status of a bulk import job. A successful job moves through `queued`, `imported`, and `compacted`; its rows become queryable once it’s `compacted`, not when it’s `imported`.

Allowed:`queued`, `dispatched`, `imported`, `compacted`, `failed`, `terminal_failed`

`table_id`requiredinteger

The ID of the table resolved from the supplied name.

`upload_uuid`requiredstring

The UUID of the upload.

400Bad request. Possible reasons: missing multipart boundary; missing `file_bytes`, `database`, or `table`; unparseable multipart; invalid or empty Parquet; malformed `column_metadata`; column type or mapping mismatch; or a missing time column.

`data`object

`error`string

401Unauthorized access.

`data`object

`error`string

403Forbidden. The token doesn’t have the `write` action on the target database. A token without that permission also gets `403` when the database doesn’t exist (`Not authorized to import into database`).

`data`object

`error`string

404Not found. The target table does not exist (“Table `cpu` does not exist”).

`data`object

`error`string

500Internal server error. Object store, status write, or catalog failure. In 3.12, a file whose columns don’t match the table also returns `500` with `Could not modify catalog`: a column that an explicit schema database doesn’t declare, or an unmapped string column that the table declares as a tag.

`data`object

`error`string

GET`/api/v3/enterprise/restore`

### List restores

Lists every restore for the cluster, newest first, including in-flight and completed restores.

Requires an admin (operator) token or admin user. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node; otherwise the endpoint returns `503 Service Unavailable`.

This endpoint is only available in InfluxDB 3 Enterprise.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/enterprise/restore" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Returns the list of restores.

`restores`requiredobject[]

All restores, newest first.

`backup_name`requiredstring

The source backup name.

`completed_at`string \<date-time\>

The completion timestamp. Omitted when the restore is not complete.

`created_at`requiredstring \<date-time\>

When the restore started.

`restore_id`requiredstring

The restore handle.

`status`requiredstring

The status of a backup or restore.

Allowed:`in_progress`, `completed`, `failed`

`total_files`requiredinteger \<int64\>

The number of files.

`total_size_bytes`requiredinteger \<int64\>

The total size in bytes.

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

500Internal server error. Listing restores failed.

`data`object

`error`string

503Service unavailable. The restore engine is not present on this node.

`data`object

`error`string

POST`/api/v3/enterprise/restore`

### Start a restore

Registers and asynchronously starts a restore from a named backup. Returns a `restore_id` handle for tracking and cancellation.

Restores run asynchronously. Poll [Get a restore](#operation/GetEnterpriseRestoreById) to track progress. Only one restore can run cluster-wide at a time; if a restore is already running, this endpoint returns `409 Conflict`.

Requires an admin (operator) token. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node; otherwise the endpoint returns `503 Service Unavailable`.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Request bodyrequired

Content-Type:`application/json`

`backup_name`requiredstring

The name of the backup to restore from. Must not be empty.

Example request body

```json
{
  "backup_name": "nightly-backup"
}
```

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/enterprise/restore" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"backup_name":"nightly-backup"}'
```

#### Responses

202Accepted. The restore has started.

`restore_id`requiredstring

The handle used to track or cancel the restore.

`status`requiredstring

The status of a newly started restore. Always `in_progress`.

Allowed:`in_progress`

Example request body

```json
{
  "restore_id": "01J8X9Z0ABCDEF",
  "status": "in_progress"
}
```

400Bad request. `backup_name` is empty.

`data`object

`error`string

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

409Conflict. A restore is already running. Only one restore can run at a time.

`data`object

`error`string

503Service unavailable. The restore engine is not present on this node, or the restore lease could not be acquired.

`data`object

`error`string

GET`/api/v3/enterprise/restore/{id}`

### Get a restore

Reports a restore’s state by `restore_id`. Reads the persisted manifest, so it works for in-flight and completed restores.

Requires an admin (operator) token or admin user. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node; otherwise the endpoint returns `503 Service Unavailable`.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Parameters

##### Path parameters

`id`requiredstring

The `restore_id` returned when the restore started.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/enterprise/restore/{id}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Returns the restore status.

`backup_name`requiredstring

The source backup name.

`completed_at`string \<date-time\>

The completion timestamp. Null when the restore is not complete.

`created_at`requiredstring \<date-time\>

When the restore started.

`restore_id`requiredstring

The restore handle.

`status`requiredstring

The status of a backup or restore.

Allowed:`in_progress`, `completed`, `failed`

`total_files`requiredinteger \<int64\>

The number of files.

`total_size_bytes`requiredinteger \<int64\>

The total size in bytes.

Example request body

```json
{
  "backup_name": "nightly-backup",
  "completed_at": null,
  "created_at": "2025-06-16T03:00:00Z",
  "restore_id": "01J8X9Z0ABCDEF",
  "status": "in_progress",
  "total_files": 128,
  "total_size_bytes": 524288000
}
```

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

404Not found. No restore exists with that ID.

`data`object

`error`string

503Service unavailable. The restore engine is not present on this node.

`data`object

`error`string

DELETE`/api/v3/enterprise/restore/{id}`

### Cancel a running restore

Cancels an in-flight restore by `restore_id`.

Requires an admin (operator) token or admin user. Requires the upgraded storage engine (enabled with the `--use-pacha-tree` flag) present on a compactor node.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Parameters

##### Path parameters

`id`requiredstring

The `restore_id` returned when the restore started.

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "https://localhost:8181/api/v3/enterprise/restore/{id}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

204No content. The cancellation has been accepted.

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

404Not found. No restore exists with that ID, the restore is already completed, or the restore engine is not present on this node.

`data`object

`error`string

GET`/api/v3/enterprise/upgrade/parquet_cleanup`

### Get Parquet cleanup status

Returns the current or most recent Parquet cleanup state for the cluster.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Related

* [influxdb3 manage cleanup-parquet](/influxdb3/enterprise/reference/cli/influxdb3/manage/cleanup-parquet/)

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/enterprise/upgrade/parquet_cleanup" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Returns the current Parquet cleanup state.

`bytes_deleted`requiredinteger \<int64\>

Total size, in bytes, of the deleted files.
Always `0` in `dry_run` mode.

`bytes_matched`requiredinteger \<int64\>

Total size, in bytes, of the matched files.

`completed_at_ns`integer \<int64\>

When the cleanup finished, in nanoseconds since the Unix epoch.

`files_deleted`requiredinteger \<int64\>

Number of files deleted so far.
Always `0` in `dry_run` mode.

`files_failed`requiredinteger \<int64\>

Number of files the cleanup failed to delete.

`files_matched`requiredinteger \<int64\>

Number of files identified as Parquet-era data to delete.

`files_scanned`requiredinteger \<int64\>

Number of files the cleanup has scanned so far.

`last_message`string

The most recent human-readable status message, if any.

`mode`requiredstring

Whether this cleanup deletes data or only reports what it would delete.

Allowed:`delete`, `dry_run`

`requested_at_ns`integer \<int64\>

When the cleanup was requested, in nanoseconds since the Unix epoch.

`requested_by`string

The node that accepted the cleanup request, if recorded.

`started_at_ns`integer \<int64\>

When the cleanup started running, in nanoseconds since the Unix epoch.

`status`requiredstring

The cleanup’s current status.

Allowed:`requested`, `running`, `completed`, `failed`

`updated_at_ns`integer \<int64\>

When this status was last updated, in nanoseconds since the Unix epoch.

Example request body

```json
{
  "bytes_deleted": 4294967296,
  "bytes_matched": 4294967296,
  "completed_at_ns": 1735689900000000000,
  "files_deleted": 812,
  "files_failed": 0,
  "files_matched": 812,
  "files_scanned": 1024,
  "last_message": null,
  "mode": "delete",
  "requested_at_ns": 1735689600000000000,
  "requested_by": "node-1",
  "started_at_ns": 1735689601000000000,
  "status": "completed",
  "updated_at_ns": 1735689900000000000
}
```

401Unauthorized access.

`data`object

`error`string

404No Parquet cleanup has ever been requested on this cluster.

POST`/api/v3/enterprise/upgrade/parquet_cleanup`

### Request Parquet cleanup after a storage engine upgrade

Requests removal of the Parquet-era data left behind by a completed Parquet-to-PachaTree storage engine upgrade. Any node in the cluster accepts the request. The compactor node executes it.

Requires the cluster to be fully on the upgraded (PachaTree) storage engine, with the Parquet-to-PachaTree upgrade already complete. Use `dry_run` to count and size the data a real cleanup would delete without deleting anything.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Related

* [influxdb3 manage cleanup-parquet](/influxdb3/enterprise/reference/cli/influxdb3/manage/cleanup-parquet/)

#### Request body

Content-Type:`application/json`

`dry_run`boolean

When `true`, only count and size the Parquet-era data a real cleanup would delete.
Delete nothing.

Example request body

```json
{
  "dry_run": false
}
```

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/enterprise/upgrade/parquet_cleanup" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"dry_run":false}'
```

#### Responses

202Success. The cleanup started, is already running, or already completed.

`state`requiredstring

The outcome of this cleanup request.

Allowed:`started`, `already_running`, `already_completed`

`status`requiredobject

Point-in-time view of the durable Parquet cleanup state.
Returned by `GET /api/v3/enterprise/upgrade/parquet_cleanup` and embedded in the POST response.

Example:`{"bytes_deleted":4294967296,"bytes_matched":4294967296,"completed_at_ns":1735689900000000000,"files_deleted":812,"files_failed":0,"files_matched":812,"files_scanned":1024,"last_message":null,"mode":"delete","requested_at_ns":1735689600000000000,"requested_by":"node-1","started_at_ns":1735689601000000000,"status":"completed","updated_at_ns":1735689900000000000}`

`bytes_deleted`requiredinteger \<int64\>

Total size, in bytes, of the deleted files.
Always `0` in `dry_run` mode.

`bytes_matched`requiredinteger \<int64\>

Total size, in bytes, of the matched files.

`completed_at_ns`integer \<int64\>

When the cleanup finished, in nanoseconds since the Unix epoch.

`files_deleted`requiredinteger \<int64\>

Number of files deleted so far.
Always `0` in `dry_run` mode.

`files_failed`requiredinteger \<int64\>

Number of files the cleanup failed to delete.

`files_matched`requiredinteger \<int64\>

Number of files identified as Parquet-era data to delete.

`files_scanned`requiredinteger \<int64\>

Number of files the cleanup has scanned so far.

`last_message`string

The most recent human-readable status message, if any.

`mode`requiredstring

Whether this cleanup deletes data or only reports what it would delete.

Allowed:`delete`, `dry_run`

`requested_at_ns`integer \<int64\>

When the cleanup was requested, in nanoseconds since the Unix epoch.

`requested_by`string

The node that accepted the cleanup request, if recorded.

`started_at_ns`integer \<int64\>

When the cleanup started running, in nanoseconds since the Unix epoch.

`status`requiredstring

The cleanup’s current status.

Allowed:`requested`, `running`, `completed`, `failed`

`updated_at_ns`integer \<int64\>

When this status was last updated, in nanoseconds since the Unix epoch.

401Unauthorized access.

`data`object

`error`string

409The cluster isn’t on the upgraded storage engine, no Parquet-to-PachaTree upgrade was ever recorded, the upgrade hasn’t completed, or a cleanup is already active in a different mode (dry run vs. delete).

POST`/api/v3/enterprise/upgrade/retry_parquet_to_pacha_tree`

### Retry a failed Parquet-to-PachaTree upgrade

Resets a Parquet-to-PachaTree storage engine upgrade that latched to a `failed` state, so it resumes the next time a compactor node starts with `--upgrade-pacha-tree`.

Re-checks every previously failed upgrade source against the catalog and object store: sources that are still readable are requeued, sources whose table or database was dropped are recorded as skipped, and sources that can’t be read back are left unresolved for the next retry.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Related

* [influxdb3 manage retry-upgrade-to-pacha-tree](/influxdb3/enterprise/reference/cli/influxdb3/manage/retry-upgrade-to-pacha-tree/)

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/enterprise/upgrade/retry_parquet_to_pacha_tree" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Returns a summary of what the retry changed.

`entries_already_converted`requiredinteger \<int64\>

Entries whose sequence already held converted data.
Recorded as imported instead of skipped.

`entries_already_skipped`requiredinteger \<int64\>

Terminal failures that were already recorded as skips.

`entries_inspected`requiredinteger \<int64\>

Terminal failures the retry re-checked against the catalog and object store.

`entries_requeued`requiredinteger \<int64\>

Entries returned to the queue because their source is still readable.

`entries_skipped_source_missing`requiredinteger \<int64\>

Entries skipped because their source object no longer exists.

`entries_skipped_table_dropped`requiredinteger \<int64\>

Entries skipped because their table was dropped.

`entries_unresolved`requiredinteger \<int64\>

Entries left untouched because the object holding their sequence couldn’t be read back.
Run this endpoint again to re-attempt them.

`message`requiredstring

What to do next.

`upgrade_status`requiredstring

The status the enterprise upgrade state was left in after the retry.

Example request body

```json
{
  "entries_already_converted": 0,
  "entries_already_skipped": 0,
  "entries_inspected": 3,
  "entries_requeued": 2,
  "entries_skipped_source_missing": 1,
  "entries_skipped_table_dropped": 0,
  "entries_unresolved": 0,
  "message": "Migration state reset. Restart the compactor node with --upgrade-pacha-tree to resume the upgrade.",
  "upgrade_status": "upgrading"
}
```

401Unauthorized access.

`data`object

`error`string

409The upgrade isn’t in a state this request can act on (for example, it isn’t `failed`), or another request already reset it.

GET`/api/v3/export/databases`

### List databases available for export

Returns a list of databases that have compacted data available for Parquet export.

>
>
> **Requires the upgraded storage engine**: This endpoint requires the[upgraded storage engine](/influxdb3/enterprise/performance-preview/), which is the default for
> new clusters. On clusters created with 3.10 or earlier, run the storage engine upgrade with[`--upgrade-pacha-tree`](/influxdb3/enterprise/reference/config-options/#upgrade-pacha-tree).
>
>

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/export/databases" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Returns a list of database names.

401Unauthorized access.

`data`object

`error`string

GET`/api/v3/export/tables`

### List tables available for export

Returns a list of tables in a database that have compacted data available for Parquet export.

>
>
> **Requires the upgraded storage engine**: This endpoint requires the[upgraded storage engine](/influxdb3/enterprise/performance-preview/), which is the default for
> new clusters. On clusters created with 3.10 or earlier, run the storage engine upgrade with[`--upgrade-pacha-tree`](/influxdb3/enterprise/reference/config-options/#upgrade-pacha-tree).
>
>

#### Parameters

##### Query parameters

`db`requiredstring

The name of the database.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/export/tables?db=DB" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Returns a list of table names.

401Unauthorized access.

`data`object

`error`string

404Database not found.

GET`/api/v3/export/window_data`

### Export window data as Parquet

Downloads compacted data for the specified windows as a tar archive containing Parquet files.

>
>
> **Requires the upgraded storage engine**: This endpoint requires the[upgraded storage engine](/influxdb3/enterprise/performance-preview/), which is the default for
> new clusters. On clusters created with 3.10 or earlier, run the storage engine upgrade with[`--upgrade-pacha-tree`](/influxdb3/enterprise/reference/config-options/#upgrade-pacha-tree).
>
>

#### Parameters

##### Query parameters

`db`requiredstring

The name of the database.

`table`requiredstring

The table name.

`windows`string

Comma-separated list of window dates to export (for example, `2026-01-15,2026-01-16`).
If omitted, exports all available windows.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/export/window_data?db=DB&table=TABLE" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Returns a tar archive containing Parquet files.

401Unauthorized access.

`data`object

`error`string

404Database, table, or window not found.

GET`/api/v3/export/windows`

### List compacted windows for a table

Returns a list of compacted 24-hour UTC windows for a table.
Each window represents a time range of compacted data that can be exported as Parquet.

>
>
> **Requires the upgraded storage engine**: This endpoint requires the[upgraded storage engine](/influxdb3/enterprise/performance-preview/), which is the default for
> new clusters. On clusters created with 3.10 or earlier, run the storage engine upgrade with[`--upgrade-pacha-tree`](/influxdb3/enterprise/reference/config-options/#upgrade-pacha-tree).
>
>

#### Parameters

##### Query parameters

`db`requiredstring

The name of the database.

`table`requiredstring

The table name.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/export/windows?db=DB&table=TABLE" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Returns a list of compacted 24-hour windows.

401Unauthorized access.

`data`object

`error`string

404Database or table not found.

POST`/api/v3/isAuthorized`

### Check whether the caller is authorized for an action

Reports whether the calling user may perform the single action named in the request body.

A denied action returns `200` with `authorized: false`.
A `403` response means the caller can’t use this endpoint.

#### Request bodyrequired

Content-Type:`application/json`

`createAdminToken`boolean

`createDatabase`boolean

`createRole`boolean

`createToken`boolean

`createUser`boolean

`deleteAdminToken`boolean

`deleteDatabase`object

`identifier`string

Resource name. Required when `scope` is `identifier`; not allowed when `scope` is `all`.

`scope`requiredstring

Allowed:`all`, `identifier`

`deleteRole`boolean

`deleteToken`boolean

`deleteUser`boolean

`describeDatabase`object

`identifier`string

Resource name. Required when `scope` is `identifier`; not allowed when `scope` is `all`.

`scope`requiredstring

Allowed:`all`, `identifier`

`readDatabase`object

`identifier`string

Resource name. Required when `scope` is `identifier`; not allowed when `scope` is `all`.

`scope`requiredstring

Allowed:`all`, `identifier`

`readRole`boolean

`readSystem`object

`identifier`string

Resource name. Required when `scope` is `identifier`; not allowed when `scope` is `all`.

`scope`requiredstring

Allowed:`all`, `identifier`

`readToken`boolean

`readUser`boolean

`updateRole`boolean

`updateUser`boolean

`writeDatabase`object

`identifier`string

Resource name. Required when `scope` is `identifier`; not allowed when `scope` is `all`.

`scope`requiredstring

Allowed:`all`, `identifier`

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/isAuthorized" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "createAdminToken": false,
  "createDatabase": false,
  "createRole": false,
  "createToken": false,
  "createUser": false,
  "deleteAdminToken": false,
  "deleteDatabase": {
    "identifier": "IDENTIFIER",
    "scope": "all"
  },
  "deleteRole": false,
  "deleteToken": false,
  "deleteUser": false,
  "describeDatabase": {
    "identifier": "IDENTIFIER",
    "scope": "all"
  },
  "readDatabase": {
    "identifier": "IDENTIFIER",
    "scope": "all"
  },
  "readRole": false,
  "readSystem": {
    "identifier": "IDENTIFIER",
    "scope": "all"
  },
  "readToken": false,
  "readUser": false,
  "updateRole": false,
  "updateUser": false,
  "writeDatabase": {
    "identifier": "IDENTIFIER",
    "scope": "all"
  }
}'
```

#### Responses

200The check was evaluated.`authorized` is `false` when the caller isn’t permitted to perform the action.

`authorized`requiredboolean

400Bad request. The body must name exactly one action; boolean actions must be `true`.

401Unauthorized access.

`data`object

`error`string

403Forbidden. Only user subjects can call this endpoint; token subjects receive `403`.

GET`/api/v3/loadcap/profiles`

### List load capture profiles

Returns load capture profiles stored by a query-capable Enterprise node that has the upgraded storage engine and an explicit `--mode` setting that includes `query`.

This endpoint requires an admin token.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/loadcap/profiles" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Load capture profiles.

401Unauthorized access.

`data`object

`error`string

403Forbidden. An admin token is required.

404Load capture is unavailable because this node does not use the upgraded storage engine with an explicit `--mode` setting that includes `query`.

GET`/api/v3/loadcap/profiles/{profile_id}`

### Retrieve load capture profile details

Returns file counts, total size, and an anonymized catalog summary for a load capture profile. The response is the same as the profile preview.

This endpoint requires an admin token.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/loadcap/profiles/{profile_id}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Load capture profile details.

`catalog_summary`object

Anonymized catalog snapshot taken when the capture started, including databases, tables, columns, and node metadata. Null for `query`-only captures.

`file_count`integer

Total number of files in the profile archive.

`profile_id`string \<uuid\>

Identifier of the load capture profile.

`query_count`integer

Number of captured queries in the profile.

`total_size_bytes`integer

Total size of the profile archive contents, in bytes.

`wal_file_count`integer

Number of anonymized write-ahead log (`.pt`) files in the profile.

401Unauthorized access.

`data`object

`error`string

403Forbidden. An admin token is required.

404The profile does not exist, or load capture is unavailable because this node does not use the upgraded storage engine with an explicit `--mode` setting that includes `query`.

DELETE`/api/v3/loadcap/profiles/{profile_id}`

### Delete a load capture profile

Deletes a load capture profile and its stored artifacts from object storage.

This endpoint requires an admin token.

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "https://localhost:8181/api/v3/loadcap/profiles/{profile_id}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200The profile was deleted.

401Unauthorized access.

`data`object

`error`string

403Forbidden. An admin token is required.

404The profile does not exist, or load capture is unavailable because this node does not use the upgraded storage engine with an explicit `--mode` setting that includes `query`.

409The profile is still capturing. Wait for it to finish (or its status to catch up to `complete`), then retry.

GET`/api/v3/loadcap/profiles/{profile_id}/download`

### Download a load capture profile

Downloads the load capture profile as a gzipped tar archive containing the anonymized capture artifacts—`catalog.json` and `.pt` write-ahead log files for `write` and `both` captures, and `queries.json.zst` for `query` and `both` captures.

This endpoint requires an admin token.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/loadcap/profiles/{profile_id}/download" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200The profile archive. The response `Content-Type` is `application/gzip` and `Content-Disposition` provides the `{profile_id}.tar.gz` filename.

401Unauthorized access.

`data`object

`error`string

403Forbidden. An admin token is required.

404The profile does not exist, or load capture is unavailable because this node does not use the upgraded storage engine with an explicit `--mode` setting that includes `query`.

GET`/api/v3/loadcap/profiles/{profile_id}/files`

### List files in a load capture profile

Returns the name, size, and type of each file stored in a load capture profile.

This endpoint requires an admin token.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/loadcap/profiles/{profile_id}/files" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Files in the load capture profile.

401Unauthorized access.

`data`object

`error`string

403Forbidden. An admin token is required.

404The profile does not exist, or load capture is unavailable because this node does not use the upgraded storage engine with an explicit `--mode` setting that includes `query`.

GET`/api/v3/loadcap/profiles/{profile_id}/files/{filename}`

### Download a single file from a load capture profile

Downloads one anonymized file from a load capture profile—for example, `catalog.json`, `queries.json.zst`, or a `.pt` write-ahead log file.

This endpoint requires an admin token.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/loadcap/profiles/{profile_id}/files/{filename}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200The file contents. The response `Content-Type` is `application/octet-stream` and `Content-Disposition` provides the filename.

401Unauthorized access.

`data`object

`error`string

403Forbidden. An admin token is required.

404The profile or file does not exist, or load capture is unavailable because this node does not use the upgraded storage engine with an explicit `--mode` setting that includes `query`.

GET`/api/v3/loadcap/profiles/{profile_id}/preview`

### Preview a load capture profile

Returns file counts, total size, and an anonymized catalog summary for a load capture profile without downloading the archive. For `query`-only captures, `catalog_summary` is null.

This endpoint requires an admin token.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/loadcap/profiles/{profile_id}/preview" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Load capture profile preview.

`catalog_summary`object

Anonymized catalog snapshot taken when the capture started, including databases, tables, columns, and node metadata. Null for `query`-only captures.

`file_count`integer

Total number of files in the profile archive.

`profile_id`string \<uuid\>

Identifier of the load capture profile.

`query_count`integer

Number of captured queries in the profile.

`total_size_bytes`integer

Total size of the profile archive contents, in bytes.

`wal_file_count`integer

Number of anonymized write-ahead log (`.pt`) files in the profile.

401Unauthorized access.

`data`object

`error`string

403Forbidden. An admin token is required.

404The profile does not exist, or load capture is unavailable because this node does not use the upgraded storage engine with an explicit `--mode` setting that includes `query`.

POST`/api/v3/loadcap/start`

### Start a load capture

Starts a timed capture of write requests, query requests, or both on a query-capable Enterprise node that has the upgraded storage engine and an explicit `--mode` setting that includes `query`.

Only one capture can run at a time on a node. This endpoint requires an admin token.

#### Request bodyrequired

Content-Type:`application/json`

`duration`requiredstring

Capture duration using seconds, minutes, or hours. The maximum duration is one hour.

Example:`"5m"`

`type`requiredstring

The request types to capture.

Allowed:`write`, `query`, `both`

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/loadcap/start" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "duration": "5m",
  "type": "write"
}'
```

#### Responses

200Load capture started.

`profile_id`requiredstring \<uuid\>

Identifier of the new load capture profile.

400Invalid capture type or duration.

401Unauthorized access.

`data`object

`error`string

403Forbidden. An admin token is required.

404Load capture is unavailable because this node does not use the upgraded storage engine with an explicit `--mode` setting that includes `query`.

409A load capture is already running on this node.

GET`/api/v3/roles`

### 

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/roles" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success

GET`/api/v3/roles_by_name/{roleName}`

### Get a role by name

Returns the role with the specified name.

Requires a token or user with permission to read roles.

This endpoint is only available in InfluxDB 3 Enterprise. User authentication is a preview feature enabled by setting `--without-user-auth false`.

#### Parameters

##### Path parameters

`roleName`requiredstring

The name of the role to retrieve.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/roles_by_name/{roleName}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Returns the matching role.

`createdAt`requiredinteger \<int64\>

The Unix timestamp (seconds) when the role was created.

`description`string

The role description.

`id`requiredinteger \<int64\>

The numeric ID of the role.

`isRequiredRole`requiredboolean

Whether the role is a required role.

`name`requiredstring

The role name.

`updatedAt`requiredinteger \<int64\>

The Unix timestamp (seconds) when the role was last updated.

Example request body

```json
{
  "createdAt": 1717000000,
  "id": 1,
  "isRequiredRole": false,
  "name": "read-write",
  "updatedAt": 1717000000
}
```

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

404Not found. No role exists with the specified name.

`data`object

`error`string

GET`/api/v3/roles/{id}/permissions`

### Get a role's permissions

Returns the permissions granted to the role with the specified ID.

Requires a token or user with permission to read roles.

This endpoint is only available in InfluxDB 3 Enterprise. User authentication is a preview feature enabled by setting `--without-user-auth false`.

#### Parameters

##### Path parameters

`id`requiredinteger \<int64\>

The ID of the role.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/roles/{id}/permissions" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Returns the role’s permissions.

`permissions`requiredobject[]

The permissions granted to the role.

`actions`requiredstring[]

The granted actions (snake\_case) for this resource type.

`allResources`boolean

Database permissions only. `true` when the permission applies to all databases.

`identifiers`string[]

Database permissions only. Specific database names the permission targets. Empty when `allResources` is `true`.

`resourceType`requiredstring

The resource category the permission applies to.

Allowed:`database`, `token`, `user`, `role`, `admin_token`

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

404Not found. No role exists with the specified ID.

`data`object

`error`string

GET`/api/v3/row_delete_requests`

### 

#### Parameters

##### Query parameters

`db`string

`table`string

`disposition`string

`min_sequence`integer

`max_sequence`integer

`include_progress`boolean

Default: (default)

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/row_delete_requests" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success

POST`/api/v3/row_delete_requests`

### 

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/row_delete_requests" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success

POST`/api/v3/row_delete_requests/{seq}/abort`

### Abort a pending row-delete request

Aborts a pending row-delete request identified by its sequence number. Returns the updated request with a disposition of `aborted`.

Requires a token or user with `delete` permission on the database that the row-delete request targets.

This endpoint is only available in InfluxDB 3 Enterprise.

#### Parameters

##### Path parameters

`seq`requiredinteger \<int64\>

The sequence number of the row-delete request to abort.

#### Request bodyrequired

Content-Type:`application/json`

`reason`requiredstring

The reason for aborting the row-delete request.

Example request body

```json
{
  "reason": "Predicate was too broad"
}
```

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/row_delete_requests/{seq}/abort" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"reason":"Predicate was too broad"}'
```

#### Responses

200Success. Returns the aborted row-delete request.

`abort_reason`string

The reason the request was aborted. Present only for aborted requests.

`aborted_at`integer \<int64\>

The Unix timestamp (seconds) when the request was aborted. Present only for aborted requests.

`completed_at`integer \<int64\>

The Unix timestamp (seconds) when the request completed. Present only for completed requests.

`created_at`requiredinteger \<int64\>

The Unix timestamp (seconds) when the request was created.

`db_id`requiredinteger \<int64\>

The numeric ID of the target database.

`db_name`requiredstring

The name of the target database.

`db_name_stale`requiredboolean

Whether the database name no longer matches the current catalog state for the stored database ID.

`delete_predicate`requiredstring

The predicate that selects rows to delete.

`disposition`requiredstring

The current disposition of the request: `pending`, `completed`, or `aborted`.

`max_time`integer \<int64\>

The maximum timestamp (nanoseconds) of the delete range.

`min_time`integer \<int64\>

The minimum timestamp (nanoseconds) of the delete range.

`progress`object

Progress tracking for a single row-delete request.

`in_range`requiredobject

Per-level progress counts for run sets that overlap the delete criteria.

`l1`requiredobject

Progress for a single compaction level.

`l2`requiredobject

Progress for a single compaction level.

`l3`requiredobject

Progress for a single compaction level.

`l4`requiredobject

Progress for a single compaction level.

`out_of_range`requiredobject

Progress counts for run sets outside the delete criteria that require only watermark updates.

`processed`requiredinteger \<int64\>

The number of out-of-range run sets processed.

`total`requiredinteger \<int64\>

The total number of out-of-range run sets.

`sequence_id`requiredinteger \<int64\>

The sequence number of the row-delete request.

`sequence`requiredinteger \<int64\>

The sequence number of the row-delete request.

`table_id`requiredinteger \<int64\>

The numeric ID of the target table.

`table_name`requiredstring

The name of the target table.

`table_name_stale`requiredboolean

Whether the table name no longer matches the current catalog state for the stored table ID.

Example request body

```json
{
  "abort_reason": "Predicate was too broad",
  "aborted_at": 1717000100,
  "created_at": 1717000000,
  "db_id": 1,
  "db_name": "sensors",
  "db_name_stale": false,
  "delete_predicate": "room = 'kitchen'",
  "disposition": "aborted",
  "sequence": 42,
  "table_id": 3,
  "table_name": "home",
  "table_name_stale": false
}
```

400

Request failed. Possible reasons:

* Invalid database name
* Malformed request body
* Invalid timestamp precision

`data`object

`error`string

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

404Not found. No row-delete request exists with the specified sequence number.

`data`object

`error`string

GET`/api/v3/users`

### 

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/users" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success

POST`/api/v3/users`

### 

#### Request bodyrequired

Content-Type:`application/json`

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/users" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json"
```

#### Responses

200Success

GET`/api/v3/users_by_oauth_id/{oauth_id}`

### Get a user by OAuth identity-provider ID

Returns the user associated with the specified OAuth identity-provider ID. Requires the server to be configured with an OAuth validator.

Requires a token or user with permission to read users.

This endpoint is only available in InfluxDB 3 Enterprise. User authentication is a preview feature enabled by setting `--without-user-auth false`.

#### Parameters

##### Path parameters

`oauth_id`requiredstring

The OAuth identity-provider ID of the user.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/users_by_oauth_id/{oauth_id}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Returns the matching user.

`createdAt`requiredinteger \<int64\>

The Unix timestamp (seconds) when the user was created.

`deletedAt`integer \<int64\>

The Unix timestamp (seconds) when the user was deleted. Present only for deleted users.

`displayName`string

The user’s display name.

`oauthId`string

The user’s OAuth identity-provider ID. Present when the user has an OAuth login identity.

`operatorToken`string

The operator token. Returned only when creating the initial user.

`requiresPasswordReset`boolean

Whether the user must reset their password on next login. Present when the user has a username and password login identity.

`updatedAt`requiredinteger \<int64\>

The Unix timestamp (seconds) when the user was last updated.

`userId`requiredinteger \<int64\>

The numeric ID of the user.

`username`string

The user’s username. Present when the user has a username and password login identity.

Example request body

```json
{
  "createdAt": 1717000000,
  "displayName": "Jane Smith",
  "requiresPasswordReset": false,
  "updatedAt": 1717000000,
  "userId": 1,
  "username": "jsmith"
}
```

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

404Not found. No user matches the specified OAuth ID, or OAuth is not configured on the server.

`data`object

`error`string

GET`/api/v3/users/{id}`

### 

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/users/{id}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success

POST`/api/v3/users/{id}/require-password-reset`

### Require a user to reset their password on next login

Marks the specified user as requiring a password reset. The user must set a new password before they are able to authenticate and receive a token.

Requires a token or user with permission to update users.

This endpoint is only available in InfluxDB 3 Enterprise. User authentication is a preview feature enabled by setting `--without-user-auth false`.

#### Parameters

##### Path parameters

`id`requiredinteger \<int64\>

The numeric ID of the user.

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://localhost:8181/api/v3/users/{id}/require-password-reset" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Returns the user with `requiresPasswordReset` set to `true`.

`createdAt`requiredinteger \<int64\>

The Unix timestamp (seconds) when the user was created.

`deletedAt`integer \<int64\>

The Unix timestamp (seconds) when the user was deleted. Present only for deleted users.

`displayName`string

The user’s display name.

`oauthId`string

The user’s OAuth identity-provider ID. Present when the user has an OAuth login identity.

`operatorToken`string

The operator token. Returned only when creating the initial user.

`requiresPasswordReset`boolean

Whether the user must reset their password on next login. Present when the user has a username and password login identity.

`updatedAt`requiredinteger \<int64\>

The Unix timestamp (seconds) when the user was last updated.

`userId`requiredinteger \<int64\>

The numeric ID of the user.

`username`string

The user’s username. Present when the user has a username and password login identity.

Example request body

```json
{
  "createdAt": 1717000000,
  "displayName": "Jane Smith",
  "requiresPasswordReset": false,
  "updatedAt": 1717000000,
  "userId": 1,
  "username": "jsmith"
}
```

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

404Not found. No user exists with the specified ID.

`data`object

`error`string

GET`/api/v3/users/{id}/roles`

### List all roles assigned to a user

Lists all roles assigned to the specified user.

Requires a token or user with permission to read users.

This endpoint is only available in InfluxDB 3 Enterprise. User authentication is a preview feature enabled by setting `--without-user-auth false`.

#### Parameters

##### Path parameters

`id`requiredinteger \<int64\>

The numeric ID of the user.

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/api/v3/users/{id}/roles" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success. Returns the list of roles assigned to the user.

`items`requiredobject[]

The roles assigned to the user.

`createdAt`requiredinteger \<int64\>

The Unix timestamp (seconds) when the role was created.

`description`string

The role description.

`id`requiredinteger \<int64\>

The numeric ID of the role.

`isRequiredRole`requiredboolean

Whether the role is a required role.

`name`requiredstring

The role name.

`updatedAt`requiredinteger \<int64\>

The Unix timestamp (seconds) when the role was last updated.

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

404Not found. No user exists with the specified ID.

`data`object

`error`string

PUT`/api/v3/users/{id}/roles`

### Replace all roles assigned to a user

Replaces all role assignments for the specified user with the provided list of role IDs. Roles not included in the request are removed from the user.

Requires a token or user with permission to update users.

This endpoint is only available in InfluxDB 3 Enterprise. User authentication is a preview feature enabled by setting `--without-user-auth false`.

#### Parameters

##### Path parameters

`id`requiredinteger \<int64\>

The numeric ID of the user.

#### Request bodyrequired

Content-Type:`application/json`

`roleIds`requiredinteger[]

The complete set of role IDs to assign to the user.

Example request body

```json
{
  "roleIds": [
    1,
    2
  ]
}
```

Example request[Ask AI about this](#)

```sh
curl --request PUT \
  "https://localhost:8181/api/v3/users/{id}/roles" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"roleIds":[1,2]}'
```

#### Responses

200Success. Returns the user’s updated role assignments.

`items`requiredobject[]

The roles assigned to the user.

`createdAt`requiredinteger \<int64\>

The Unix timestamp (seconds) when the role was created.

`description`string

The role description.

`id`requiredinteger \<int64\>

The numeric ID of the role.

`isRequiredRole`requiredboolean

Whether the role is a required role.

`name`requiredstring

The role name.

`updatedAt`requiredinteger \<int64\>

The Unix timestamp (seconds) when the role was last updated.

400

Request failed. Possible reasons:

* Invalid database name
* Malformed request body
* Invalid timestamp precision

`data`object

`error`string

401Unauthorized access.

`data`object

`error`string

403Access denied.

`data`object

`error`string

404Not found. No user exists with the specified ID.

`data`object

`error`string

GET`/ready`

### 

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "https://localhost:8181/ready" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200Success

#### Related

* [InfluxDB 3 API client libraries](/influxdb3/enterprise/reference/client-libraries/v3/)
