How to create an InfluxDB v2 bucket with retention

Creating an InfluxDB OSS v2 bucket with a retention period gives a workload its own storage boundary and automatic data expiration window. Use it before agents, applications, or migration jobs begin writing data that should expire after a known operational lifetime.

In InfluxDB v2, a bucket belongs to one organization and combines the storage target with the retention policy. Use a CLI session with a configured host and token profile, and name the organization explicitly when creating, listing, writing, and querying.

Retention does not delete old points the moment the clock crosses the boundary. InfluxDB removes expired shard groups during retention enforcement, so use the bucket listing to verify the configured period and a write/query smoke test to confirm the new bucket is ready for incoming data.

1. Confirm the target organization name and token access.

   $ influx org list
   ID			Name
   0f1e2d3c4b5a6978	plant-ops

   Use a token that can create buckets and later write/query the new bucket. Add --host and --token flags when an active CLI profile is not configured.

2. Create the bucket with the required retention period.

   $ influx bucket create --org plant-ops --name plant_metrics --retention 72h
   ID			Name		Retention	Shard group duration	Organization ID		Schema Type
   0a1b2c3d4e5f6789	plant_metrics	72h0m0s		24h0m0s			0f1e2d3c4b5a6978	implicit

   Use duration units such as h, d, or w. The minimum retention period is one hour. Omit --retention when the bucket should keep data indefinitely.

3. Verify the saved bucket retention period.

   $ influx bucket list --org plant-ops --name plant_metrics
   ID			Name		Retention	Shard group duration	Organization ID		Schema Type
   0a1b2c3d4e5f6789	plant_metrics	72h0m0s		24h0m0s			0f1e2d3c4b5a6978	implicit

   Retention shows the bucket data lifetime. Shard group duration is chosen automatically unless a custom shard group duration was set during bucket creation.

4. Write one test point into the new bucket.

   $ influx write --org plant-ops --bucket plant_metrics 'environment,site=plant-1 temperature=21.7'

   No output means the influx CLI accepted the write. Use a disposable measurement or tag value when testing against a production bucket.
   Related: How to write line protocol to InfluxDB v2

5. Query the test point from the new bucket.

   $ influx query --org plant-ops 'from(bucket: "plant_metrics") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "environment")'
   Result: _result
   Table: keys: [_start, _stop, _field, _measurement, site]
                      _start:time                      _stop:time           _field:string     _measurement:string             site:string                      _time:time                  _value:float
   ------------------------------  ------------------------------  ----------------------  ----------------------  ----------------------  ------------------------------  ----------------------------
   2026-06-20T09:04:47Z            2026-06-20T10:04:47Z            temperature             environment              plant-1                 2026-06-20T10:04:41Z            21.7

   A returned row confirms the bucket exists, accepts writes, and is readable through the same organization and token.
   Related: How to run a Flux query in InfluxDB v2