Table

Download InfluxDB 3 Enterprise API Spec

Manage table schemas in an InfluxDB 3 Enterprise database.

POST /api/v3/configure/distinct_cache

Create distinct cache

Creates a distinct cache for a table.

Request body required

Content-Type: application/json

columns required string[]

db required string

max_age integer

Optional maximum age in seconds.

max_cardinality integer

Optional maximum cardinality.

name string

Optional cache name.

node_spec string

table required string

Example request body

{
  "columns": [
    "tag1",
    "tag2"
  ],
  "db": "mydb",
  "max_age": 3600,
  "max_cardinality": 1000,
  "table": "mytable"
}

Example request Ask AI about this

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

Responses

201 Success. The distinct cache has been created.

400

Bad request.

The server responds with status 400 if the request would overwrite an existing cache with a different configuration.

409 Conflict. A distinct cache with this configuration already exists.

DELETE /api/v3/configure/distinct_cache

Delete distinct cache

Deletes a distinct cache.

Parameters

Query parameters

db required string

The name of the database.

table required string

The name of the table containing the distinct cache.

name required string

The name of the distinct cache to delete.

Example request Ask AI about this

curl --request DELETE \
  "https://localhost:8181/api/v3/configure/distinct_cache?db=DB&table=TABLE&name=NAME" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The distinct cache has been deleted.

400 Bad request.

401 Unauthorized access.

data object

error string

404 Cache not found.

POST /api/v3/configure/last_cache

Create last cache

Creates a last cache for a table.

Request body required

Content-Type: application/json

count integer

Optional count.

db required string

key_columns string[]

Optional list of key columns.

name string

Optional cache name.

node_spec string

table required string

ttl integer

Optional time-to-live in seconds.

value_columns string[]

Optional list of value columns.

Example request body

{
  "count": 100,
  "db": "mydb",
  "key_columns": [
    "tag1"
  ],
  "table": "mytable",
  "ttl": 3600,
  "value_columns": [
    "field1"
  ]
}

Example request Ask AI about this

curl --request POST \
  "https://localhost:8181/api/v3/configure/last_cache" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"count":100,"db":"mydb","key_columns":["tag1"],"table":"mytable","ttl":3600,"value_columns":["field1"]}'

Responses

201 Success. Last cache created.

400 Bad request. A cache with this name already exists or the request is malformed.

401 Unauthorized access.

data object

error string

404 Cache not found.

DELETE /api/v3/configure/last_cache

Delete last cache

Deletes a last cache.

Parameters

Query parameters

db required string

The name of the database.

table required string

The name of the table containing the last cache.

name required string

The name of the last cache to delete.

Example request Ask AI about this

curl --request DELETE \
  "https://localhost:8181/api/v3/configure/last_cache?db=DB&table=TABLE&name=NAME" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The last cache has been deleted.

400 Bad request.

401 Unauthorized access.

data object

error string

404 Cache not found.

POST /api/v3/configure/table

Create a table

Creates a new table within a database.

Request body required

Content-Type: application/json

db required string

fields required object[]

name required string

type required string

Allowed: utf8 , int64 , uint64 , float64 , bool

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 required string

tags required string[]

Example request Ask AI about this

curl --request POST \
  "https://localhost:8181/api/v3/configure/table" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "db": "DB",
  "fields": [],
  "retention_period": "30d",
  "table": "TABLE",
  "tags": [
    "example"
  ]
}'

Responses

200 Success. The table has been created.

400 Bad request.

401 Unauthorized access.

data object

error string

404 Database not found.

PUT /api/v3/configure/table

Update a table

Updates table configuration, such as retention period.

Request body required

Content-Type: application/json

db required string

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 required string

The name of the table to update.

Example request Ask AI about this

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

200 Success. The table has been updated.

400 Bad request.

401 Unauthorized access.

data object

error string

404 Table not found.

DELETE /api/v3/configure/table

Delete a table

Soft deletes a table. The table is scheduled for deletion and unavailable for querying. Use the hard_delete_at parameter to schedule a hard deletion. Use the data_only parameter to delete data while preserving the table schema and resources.

Deleting a table cannot be undone

Deleting a table is a destructive action. Once a table is deleted, data stored in that table cannot be recovered.

Parameters

Query parameters

db required string

The name of the database.

table required string

data_only boolean

Delete only data while preserving the table schema and all associated resources (last value caches, distinct value caches). When false (default), the entire table is deleted.

hard_delete_at string <date-time>

Schedule the table for hard deletion at the specified time. If not provided, the table will be soft deleted. Use ISO 8601 format (for example, “2025-12-31T23:59:59Z”).

Also accepts special string values:

now — hard delete immediately
never — soft delete only (default behavior)
default — use the system default hard deletion time

Example request Ask AI about this

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

Responses

200 Success (no content). The table has been deleted.

401 Unauthorized access.

data object

error string

404 Table not found.

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 body required

Content-Type: application/json

columns required string[]

The columns to use for the file index.

db required string

The database name.

table string

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

Example request body

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

Example request Ask AI about this

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

200 Success. The file index has been created.

400 Bad request.

401 Unauthorized access.

data object

error string

404 Database 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 body required

Content-Type: application/json

db required string

The database name.

table string

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

Example request body

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

Example request Ask AI about this

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

200 Success. The file index has been deleted.

400 Bad request.

401 Unauthorized access.

data object

error string

404 Database, table, or file index 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.

influxdb3 update table

Parameters

Query parameters

db required string

The database name.

table required string

The table name.

duration required string

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

Example request Ask AI about this

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

204 Success. The table retention period has been set.

400 Bad request. Invalid duration format.

401 Unauthorized access.

data object

error string

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

influxdb3 update table

Parameters

Query parameters

db required string

The database name.

table required string

The table name.

Example request Ask AI about this

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

Responses

204 Success. The table retention period has been cleared.

401 Unauthorized access.

data object

error string

404 Database or table not found.

Was this page helpful?

Thank you for your feedback!

Support and feedback

Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB 3 Enterprise and this documentation. To find support, use the following resources:

Customers with an annual or support contract can contact InfluxData Support. Customers using a trial license can email trial@influxdata.com for assistance.

Edit this page Submit docs issue Submit InfluxDB 3 Enterprise issue

Create distinct cache

Request body required

Responses

Delete distinct cache

Parameters

Query parameters

Responses

Create last cache

Request body required

Responses

Delete last cache

Parameters

Query parameters

Responses

Create a table

Request body required

Responses

Update a table

Request body required

Responses

Delete a table

Deleting a table cannot be undone

Parameters

Query parameters

Responses

Create a file index

Request body required

Responses

Delete a file index

Request body required

Responses

Set table retention period

Related

Parameters

Query parameters

Responses

Clear table retention period

Related

Parameters

Query parameters

Responses

Related

Support and feedback

What is your InfluxDB 3 Enterprise URL?

Default

Custom

Thank you for your feedback!

InfluxDB 3.9: Performance upgrade preview

Telegraf Enterprise now in public beta

Telegraf Controller v0.0.6-beta now available

InfluxDB Docker latest tag changing to InfluxDB 3 Core