> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# InfluxDB

> Connect InfluxDB to CloudThinker for bucket and database inventory, retention review, and bounded time-series queries

Connect your InfluxDB instance to let [Tony](/guide/agents/tony) (Database Engineer) list what your instance stores, show how long each container keeps its data, and answer questions by querying the data itself.

InfluxDB authenticates with a single **API token**. Changing retention or creating and deleting a container happens only after you turn the write tool on and approve each change — your stored data points are never writable through this connection.

## Supported platforms

| Platform                     | Supported | Notes                                       |
| ---------------------------- | --------- | ------------------------------------------- |
| **InfluxDB OSS 2.x**         | Yes       | Buckets, organizations, and Flux            |
| **InfluxDB Cloud 2**         | Yes       | Same as OSS 2.x, hosted by InfluxData       |
| **InfluxDB 3 Core**          | Yes       | Databases, no organizations, and SQL        |
| **InfluxDB 3 Enterprise**    | Yes       | Same as Core, plus scoped read-only tokens  |
| **InfluxDB 1.x**             | No        | Predates the token API this connection uses |
| **InfluxDB Cloud Dedicated** | No        | Its management API is a separate product    |

You do not tell CloudThinker which generation you run — the **Connected** message names what it found, and that answer decides whether agents work with buckets and Flux (InfluxDB 2) or databases and SQL (InfluxDB 3).

## Prerequisites

* An **InfluxDB instance** reachable from CloudThinker over its HTTP API. Self-hosted InfluxDB 2 usually answers on `8086`, InfluxDB 3 Core on `8181`.
* An **API token** with read access to the buckets or databases you want the agent to see.
* On **InfluxDB 2 only**: the name of the **organization**, if the token reaches more than one.

## Setup

<Tabs>
  <Tab title="InfluxDB 2">
    <Steps>
      <Step title="Create a read token">
        In the InfluxDB UI, open **Load Data → API Tokens**, click **Generate**, and choose **Read/Write API Token**. Select the buckets CloudThinker should read in the **Read** pane and leave the **Write** pane empty — see the [InfluxDB 2 token guide](https://docs.influxdata.com/influxdb/v2/admin/tokens/create-token/).

        Copy the token immediately; InfluxDB shows the value once.
      </Step>

      <Step title="Add the connection in CloudThinker">
        Go to **Connections → InfluxDB** and enter:

        * **Base URL**: scheme, host, and port, such as `https://influx.example.com:8086`
        * **API token**: the token you just copied
        * **Organization**: your organization name, only if this token reaches more than one

        Click **Connect**. The **Connected** message names the generation it found, such as `InfluxDB 2 connection verified (v2.7.12)`.
      </Step>
    </Steps>
  </Tab>

  <Tab title="InfluxDB 3">
    <Steps>
      <Step title="Create a token">
        On **InfluxDB 3 Enterprise**, create a resource token scoped to read the databases you want — the narrower option and the one to prefer. On **InfluxDB 3 Core**, create an admin token with the `influxdb3` CLI:

        ```bash theme={null}
        influxdb3 create token --admin --name cloudthinker
        ```

        Core issues admin tokens only — read [Security](#security) before you use one; the [InfluxDB 3 Core token guide](https://docs.influxdata.com/influxdb3/core/admin/tokens/admin/create/) shows other creation methods. Copy the token from the command output; it is shown once.
      </Step>

      <Step title="Add the connection in CloudThinker">
        Go to **Connections → InfluxDB** and enter:

        * **Base URL**: scheme, host, and port, such as `https://influx.example.com:8181`
        * **API token**: the token you just created
        * **Organization**: leave blank — InfluxDB 3 has no organizations

        Click **Connect**. The **Connected** message names the generation it found.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Warning>
  Enter the **Base URL only**: scheme, host, port, and an optional reverse-proxy prefix such as `/influx`. Do not paste an API endpoint, query string, fragment, or embedded credentials — anything in the URL is carried into every request. Use `https` for any public or remote endpoint, because the token is sent on every request.
</Warning>

## Connection details

| Field            | Description                                                                 | Required |
| ---------------- | --------------------------------------------------------------------------- | -------- |
| **Base URL**     | Scheme, host, port, and optional reverse-proxy prefix                       | Yes      |
| **API token**    | An InfluxDB API token with read access to the containers you want seen      | Yes      |
| **Organization** | InfluxDB 2 only, and only when the token reaches more than one organization | No       |

## Required permissions

The token needs **read** access to the containers you want inspected, and nothing more:

| Generation                | Minimum                             | How to grant it                                                        |
| ------------------------- | ----------------------------------- | ---------------------------------------------------------------------- |
| **InfluxDB 2**            | Read on the buckets you want seen   | A Read/Write API Token with buckets selected in the **Read** pane only |
| **InfluxDB 3 Enterprise** | Read on the databases you want seen | A resource token scoped to those databases                             |
| **InfluxDB 3 Core**       | Not available                       | Core issues admin tokens only                                          |

Write access is needed only if you also turn the write tool on, and then only to change retention and create or delete a container. It is never needed to read.

<Tip>
  Create a dedicated token for CloudThinker rather than reusing one — it keeps the access visible and revocable on its own. On InfluxDB 3 Core, any token has full admin permissions on the server; prefer Enterprise or InfluxDB 2 when a scoped token matters.
</Tip>

## Agent capabilities

Once connected, Tony can read what your instance holds.

| Capability              | Description                                                                         |
| ----------------------- | ----------------------------------------------------------------------------------- |
| **Container inventory** | List the buckets or databases on the instance, with the retention set on each       |
| **Retention review**    | Name every container that keeps its data forever                                    |
| **One named container** | Confirm a single bucket or database by name                                         |
| **Bounded queries**     | Answer a question from the data itself, in Flux on InfluxDB 2 and SQL on InfluxDB 3 |

Answers are bounded: the inventory reads at most 25 containers, and a query returns at most 50 rows by default within a 60-second budget; the agent says when a result was cut short. A retention the token cannot read is reported as **unreadable**, not merged into the forever count.

### Verify the connection

```text theme={null}
@tony list the InfluxDB buckets or databases and the retention on each
```

### Example prompts

```text theme={null}
@tony #report which InfluxDB containers keep their data forever and explain the resulting storage exposure
@tony #report the number of points written to the telemetry bucket in the last 24 hours
@tony #recommend a retention policy for our highest-volume container
```

## Write access

The connection ships with writes turned **off**. A workspace owner turns the write tool on, and even then the agent states the exact container and change and waits for your approval every time. Reads never ask.

| Action                                    | Allowed                                        |
| ----------------------------------------- | ---------------------------------------------- |
| Change a container's retention            | Yes, after approval                            |
| Create or delete a bucket or database     | Yes, after approval                            |
| Write, edit, or delete stored data points | **Never** — the connection has no path to them |

<Warning>
  Shortening retention deletes data immediately: every point older than the new window expires, with no copy kept. Deleting a bucket on InfluxDB 2 removes its data at once with no undo; InfluxDB 3 soft-deletes and frees the storage later. The token is still the real limit — turning the tool on grants nothing the token does not already have.
</Warning>

## Troubleshooting

<Accordion title="InfluxDB rejected this API token">
  The token was revoked, incompletely copied, or belongs to a different instance. InfluxDB shows a token's value only at creation, so create a new token and reconnect.
</Accordion>

<Accordion title="The token has no read permission">
  The token is valid but its permissions do not cover the buckets or databases. Widen its read scope in InfluxDB, or create a token that includes them, then test again.
</Accordion>

<Accordion title="The URL did not answer, or did not answer as InfluxDB">
  Nothing answered, or something answered that was not the InfluxDB API — including an InfluxDB 1.x instance or the InfluxDB Cloud Dedicated management API, neither of which is supported. Check that the instance is running and reachable from CloudThinker, that the **Base URL** points at the InfluxDB HTTP port — usually `8086` on InfluxDB 2 and `8181` on InfluxDB 3 Core — and that any path is only the proxy prefix.
</Accordion>

<Accordion title="A redirect was refused">
  Something in front of the instance is steering the API call to another host. CloudThinker never follows it, because that would send your token somewhere you did not name. Point the connection at the host that serves InfluxDB itself.
</Accordion>

<Accordion title="An agent says the token reaches several organizations">
  On InfluxDB 2, a token that reaches more than one organization leaves no bucket or query unambiguously scoped. Reconnect and set the **Organization** field to the one you want.
</Accordion>

<Accordion title="An agent refuses to run a query">
  Statements that would stop being reads are refused: Flux that writes points or opens outbound connections on InfluxDB 2, and SQL that inserts, changes, or removes anything on InfluxDB 3. Nothing was sent to your instance. Rewrite the question as a read.
</Accordion>

<Accordion title="An agent reports fewer containers than the InfluxDB UI shows">
  Either the token cannot see the rest, or the inventory stopped at its limit of 25. Check the token's read scope first, then ask about the specific bucket or database by name.
</Accordion>

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **The token is the whole credential** — there is no second factor, so scope it to the containers you want seen and treat an InfluxDB 3 Core token as an admin credential.
- **Stored data points are unreachable** — no permission you grant and no switch you turn on makes your time-series data writable through CloudThinker.

## Related

<CardGroup cols={2}>
  <Card title="Prometheus Connection" icon="https://mintcdn.com/cloudthinker/wCGuHK6EQ4nmA6Df/images/icons/prometheus.svg?fit=max&auto=format&n=wCGuHK6EQ4nmA6Df&q=85&s=0866a6360993d3f82f31c0577ab2c9d2" href="/guide/connections/prometheus" width="24" height="24" data-path="images/icons/prometheus.svg">
    Metric queries, alert rules, and target health
  </Card>

  <Card title="ClickHouse Connection" icon="https://mintcdn.com/cloudthinker/PAPf7dQXz6G9xwkG/images/icons/clickhouse.svg?fit=max&auto=format&n=PAPf7dQXz6G9xwkG&q=85&s=ab9a9cd8360e654e599eac01509b8091" href="/guide/connections/clickhouse" width="24" height="24" data-path="images/icons/clickhouse.svg">
    Schema inspection and analytical query investigation
  </Card>
</CardGroup>