---
title: Table
description: Manage table schemas in an InfluxDB 3 Cloud database.
url: https://docs.influxdata.com/influxdb3/cloud/api/table/
estimated_tokens: 714
product: InfluxDB 3 Cloud
version: cloud
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb3/cloud/api/table/
---

[Download InfluxDB 3 Cloud API Spec](/openapi/influxdb3-cloud-openapi.yml)

Manage table schemas in an InfluxDB 3 Cloud database.

POST`/api/v3/configure/table`

### Create a table

Creates a new table within a database.

#### Request bodyrequired

Content-Type:`application/json`

`db`requiredstring

`fields`requiredobject[]

`name`requiredstring

`type`requiredstring

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

`tags`requiredstring[]

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "https://cluster-host.a.influxdb.io/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

200Success. The table has been created.

400Bad request.

401Unauthorized access.

`data`object

`error`string

404Database 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`requiredstring

The name of the database.

`table`requiredstring

`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](#)

```sh
curl --request DELETE \
  "https://cluster-host.a.influxdb.io/api/v3/configure/table?db=DB&table=TABLE" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

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

401Unauthorized access.

`data`object

`error`string

404Table not found.

#### Related

* [Manage tables](/influxdb3/cloud/admin/tables/)
* [InfluxDB 3 API client libraries](/influxdb3/cloud/reference/client-libraries/v3/)