--- title: Use the InfluxDB v1 API with InfluxDB Clustered description: Use InfluxDB v1 API authentication, endpoints, and tools when bringing existing 1.x workloads to InfluxDB Clustered. url: https://docs.influxdata.com/influxdb3/clustered/guides/api-compatibility/v1/ estimated_tokens: 6282 publisher: InfluxData canonical: https://docs.influxdata.com/influxdb3/clustered/guides/api-compatibility/v1/ date: '2026-05-15T15:46:14-06:00' lastmod: '2026-05-15T15:46:14-06:00' --- Use the InfluxDB v1 API `/write` and `/query` endpoints with v1 workloads that you bring to InfluxDB Clustered. The v1 endpoints work with username/password authentication and existing InfluxDB 1.x tools and code. The InfluxDB v1 API `/write` endpoint works with InfluxDB 1.x client libraries and the [Telegraf v1 Output Plugin](/telegraf/v1/plugins/#output-influxdb). The InfluxDB v1 API `/query` endpoint supports InfluxQL and third-party integrations like [Grafana](https://grafana.com). Learn how to authenticate requests, adjust request parameters for existing v1 workloads, and find compatible tools for writing and querying data stored in an InfluxDB Clustered database. * [Authenticate API requests](#authenticate-api-requests) * [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme) * [Basic authentication](#basic-authentication) * [Syntax](#syntax) * [Example](#example) * [Query string authentication](#query-string-authentication) * [Syntax](#syntax) * [Example](#example) * [Authenticate with a token scheme](#authenticate-with-a-token-scheme) * [Syntax](#syntax) * [Examples](#examples) * [Responses](#responses) * [Error examples](#error-examples) * [Write data](#write-data) * [v1 API /write parameters](#v1-api-write-parameters) * [Timestamp precision](#timestamp-precision) * [Tools for writing to the v1 API](#tools-for-writing-to-the-v1-api) * [Telegraf](#telegraf) * [Other Telegraf configuration options](#other-telegraf-configuration-options) * [Interactive clients](#interactive-clients) * [v1 CLI not supported](#v1-cli-not-supported) * [Client libraries](#client-libraries) * [Query data](#query-data) * [Tools to execute queries](#tools-to-execute-queries) * [v1 API /query parameters](#v1-api-query-parameters) * [Timestamp precision](#timestamp-precision) * [Database management with InfluxQL not supported](#database-management-with-influxql-not-supported) ## Authenticate API requests InfluxDB Clustered requires each API request to be authenticated with a[database token](/influxdb3/clustered/admin/tokens/#database-tokens). With InfluxDB v1-compatible endpoints in InfluxDB 3, you can use database tokens in InfluxDB 1.x username and password schemes, in the InfluxDB v2 `Authorization: Token` scheme, or in the OAuth `Authorization: Bearer` scheme. * [Authenticate with a username and password scheme](#authenticate-with-a-username-and-password-scheme) * [Authenticate with a token scheme](#authenticate-with-a-token-scheme) ### Authenticate with a username and password scheme With InfluxDB v1-compatible endpoints, you can use the InfluxDB 1.x convention of username and password to authenticate database reads and writes by passing a [database token](/influxdb3/clustered/admin/tokens/#database-tokens) as the `password` credential. When authenticating requests to the v1 API `/write` and `/query` endpoints, InfluxDB Clustered checks that the `password` (`p`) value is an authorized [database token](/influxdb3/clustered/admin/tokens/#database-tokens). InfluxDB Clustered ignores the `username` (`u`) parameter in the request. Use one of the following authentication schemes with clients that support Basic authentication or query parameters (that don’t support [token authentication](#authenticate-with-a-token-scheme)): * [Basic authentication](#basic-authentication) * [Query string authentication](#query-string-authentication) #### Basic authentication Use the `Authorization` header with the `Basic` scheme to authenticate v1 API `/write` and `/query` requests. When authenticating requests, InfluxDB Clustered checks that the `password` part of the decoded credential is an authorized [database token](/influxdb3/clustered/admin/tokens/#database-tokens). InfluxDB Clustered ignores the `username` part of the decoded credential. ##### Syntax ```http Authorization: Basic ``` Encode the `[USERNAME]:DATABASE_TOKEN` credential using base64 encoding, and then append the encoded string to the `Authorization: Basic` header. > [!Note] > Most HTTP clients provide a **Basic authentication** option that > accepts the `:` syntax > and encodes the credentials before sending the request. ##### Example The following example shows how to use cURL with the `Basic` authentication scheme and a [database token](/influxdb3/clustered/admin/tokens/#database-tokens): ```sh curl --get "https://cluster-host.com/query" \ --user "any:DATABASE_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM MEASUREMENT" ``` Replace the following: * `DATABASE_NAME`: your InfluxDB Clustered [database](/influxdb3/clustered/admin/databases/) * `DATABASE_TOKEN`: a [database token](/influxdb3/clustered/admin/tokens/#database-tokens) with sufficient permissions to the specified database #### Query string authentication In the URL, pass the `p` query parameter to authenticate `/write` and `/query` requests. When authenticating requests, InfluxDB Clustered checks that the `p` (*password*) value is an authorized database token and ignores the `u` (*username*) parameter. ##### Syntax ```http https://cluster-host.com/query/?[u=any]&p=DATABASE_TOKEN https://cluster-host.com/write/?[u=any]&p=DATABASE_TOKEN ``` ##### Example The following example shows how to use cURL with query string authentication and [database token](/influxdb3/clustered/admin/tokens/#database-tokens). ```sh curl --get "https://cluster-host.com/query" \ --data-urlencode "p=DATABASE_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM MEASUREMENT" ``` Replace the following: * `DATABASE_NAME`: your InfluxDB Clustered [database](/influxdb3/clustered/admin/databases/) * `DATABASE_TOKEN`: a [database token](/influxdb3/clustered/admin/tokens/#database-tokens) with sufficient permissions to the specified database ### Authenticate with a token scheme Use the `Authorization: Bearer` or the `Authorization: Token` scheme to pass a [database token](/influxdb3/clustered/admin/tokens/#database-tokens) for authenticating v1 API `/write` and `/query` requests. `Bearer` and `Token` are equivalent in InfluxDB Clustered. The `Token` scheme is used in the InfluxDB 2.x API.`Bearer` is defined by the [OAuth 2.0 Framework](https://www.rfc-editor.org/rfc/rfc6750#page-14). Support for one or the other may vary across InfluxDB API clients. Include the word `Bearer` or `Token`, a space, and your **token** value (all case-sensitive). #### Syntax ```http Authorization: Bearer DATABASE_TOKEN ``` ```http Authorization: Token DATABASE_TOKEN ``` #### Examples Use `Bearer` to authenticate a write request: ```sh curl -i "https://cluster-host.com/write?db=DATABASE_NAME&precision=s" \ --header "Authorization: Bearer DATABASE_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1641024000' ``` Use `Token` to authenticate a write request: ```sh curl -i "https://cluster-host.com/write?db=DATABASE_NAME&precision=s" \ --header "Authorization: Token DATABASE_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1641024000' ``` Replace the following: * `DATABASE_NAME`: your InfluxDB Clustered [database](/influxdb3/clustered/admin/databases/) * `DATABASE_TOKEN`: a [database token](/influxdb3/clustered/admin/tokens/#database-tokens) with sufficient permissions to the specified database ## Responses InfluxDB API responses use standard HTTP status codes. For successful writes, InfluxDB responds with a `204 No Content` status code. Error responses contain a JSON object with `code` and `message` properties that describe the error. Response body messages may differ across InfluxDB Clustered v1 API, v2 API, InfluxDB Cloud, and InfluxDB OSS. ### Error examples * **Invalid namespace name**: ``` 400 Bad Request ``` ``` { "code":"invalid", "message":"namespace name length must be between 1 and 64 characters" } ``` The `?db=` parameter value is missing in the request. Provide the [database](/influxdb3/clustered/admin/databases/) name. * **Failed to deserialize db/rp/precision** ``` 400 Bad Request ``` ``` { "code":"invalid", "message":"failed to deserialize db/rp/precision in request: unknown variant `u`, expected one of `s`, `ms`, `us`, `ns`" } ``` The `?precision=` parameter contains an unknown value. Provide a [timestamp precision](#timestamp-precision). ## Write data Write data with your existing workloads that already use the InfluxDB v1 or v1.x-compatibility `/write` API endpoint. ``` POST https://cluster-host.com/write ``` * [`/write` parameters](#v1-api-write-parameters) * [Tools for writing to the v1 API](#tools-for-writing-to-the-v1-api) #### v1 API /write parameters For InfluxDB Clustered v1 API `/write` requests, set parameters as listed in the following table: | Parameter | Allowed in | Ignored | Value | |------------------|------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `consistency` |Query string| Ignored | N/A | | `db` \* |Query string| Honored | Database name | | `precision` |Query string| Honored | [Timestamp precision](#timestamp-precision) | | `rp` |Query string|Honored, but discouraged| Retention policy | | `u` |Query string| Ignored | For [query string authentication](#query-string-authentication), any arbitrary string | | `p` |Query string| Honored |For [query string authentication](#query-string-authentication), a [database token](/influxdb3/clustered/get-started/setup/#create-a-database-token) with permission to write to the database| |`Content-Encoding`| Header | Honored | `gzip` (compressed data) or `identity` (uncompressed) | | `Authorization` | Header | Honored | `Bearer DATABASE_TOKEN`, `Token DATABASE_TOKEN`, or `Basic ` | \* = Required #### Timestamp precision Use one of the following `precision` values in v1 API `/write` requests: * `ns`: nanoseconds * `us`: microseconds * `ms`: milliseconds * `s`: seconds * `m`: minutes * `h`: hours ### Tools for writing to the v1 API The following tools work with the InfluxDB Clustered `/write` endpoint: * [Telegraf](#telegraf) * [Interactive clients](#interactive-clients) * [Client libraries](#client-libraries) #### Telegraf If you have existing v1 workloads that use Telegraf, you can use the [InfluxDB v1.x `influxdb` Telegraf output plugin](/telegraf/v1/output-plugins/influxdb/) to write data. > [!Note] > See how to [use Telegraf and the v2 API](/influxdb3/clustered/write-data/use-telegraf/) for new workloads that don’t already use the v1 API. The following table shows `outputs.influxdb` plugin parameters and values for writing to the InfluxDB Clustered v1 API: | Parameter | Ignored | Value | |------------------------|------------------------|-------------------------------------------------------------------------------------------------------------| | `database` | Honored | Database name | | `retention_policy` |Honored, but discouraged| [Duration](/influxdb3/clustered/reference/glossary/#duration) | | `username` | Ignored | String or empty | | `password` | Honored |[database token](/influxdb3/clustered/admin/tokens/#database-tokens) with permission to write to the database| | `content_encoding` | Honored | `gzip` (compressed data) or `identity` (uncompressed) | |`skip_database_creation`| Ignored | N/A (see how to [create a database](/influxdb3/clustered/admin/databases/create/)) | To configure the v1.x output plugin for writing to InfluxDB Clustered, add the following `outputs.influxdb` configuration in your `telegraf.conf` file: ```toml [[outputs.influxdb]] urls = ["https://cluster-host.com"] database = "DATABASE_NAME" skip_database_creation = true retention_policy = "" username = "ignored" password = "DATABASE_TOKEN" content_encoding = "gzip" ``` Replace the following: * `DATABASE_NAME`: your InfluxDB Clustered [database](/influxdb3/clustered/admin/databases/) * `DATABASE_TOKEN`: a [database token](/influxdb3/clustered/admin/tokens/#database-tokens) with sufficient permissions to the specified database ##### Other Telegraf configuration options `influx_uint_support`: supported in InfluxDB 3. For more plugin options, see [`influxdb`](/telegraf/v1/output-plugins/influxdb/) on GitHub. #### Interactive clients To test InfluxDB v1 API writes interactively from the command line, use common HTTP clients such as cURL and Postman. Include the following in your request: * A `db` query string parameter with the name of the database to write to. * A request body that contains a string of data in [line protocol](/influxdb3/clustered/reference/syntax/line-protocol/) syntax. * A [database token](/influxdb3/clustered/admin/tokens/#database-tokens) in one of the following authentication schemes: [Basic authentication](#basic-authentication), [query string authentication](#query-string-authentication), or [token authentication](#authenticate-with-a-token-scheme). * Optional [parameters](#v1-api-write-parameters). The following example shows how to use the **cURL** command line tool and the InfluxDB Clustered v1 API to write line protocol data to a database: ```sh curl -i 'https://cluster-host.com/write?db=DATABASE_NAME&precision=s' \ --header 'Authorization: Bearer DATABASE_TOKEN' \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1641024000' ``` Replace the following: * `DATABASE_NAME`: your InfluxDB Clustered [database](/influxdb3/clustered/admin/databases/) * `DATABASE_TOKEN`: a [database token](/influxdb3/clustered/admin/tokens/#database-tokens) with sufficient permissions to the specified database ##### v1 CLI (not supported) Don’t use the v1 CLI with InfluxDB Clustered. While it may coincidentally work, it isn’t officially supported. #### Client libraries Use language-specific [v1 client libraries](/influxdb/v1/tools/api_client_libraries/) and your custom code to write data to InfluxDB. v1 client libraries send data in [line protocol](/influxdb3/clustered/reference/syntax/line-protocol/) syntax to the v1 API `/write` endpoint. The following samples show how to configure **v1** client libraries for writing to InfluxDB Clustered: [Node.js](#nodejs)[Python](#python) Create a v1 API client using the [node-influx](/influxdb/v1/tools/api_client_libraries/#javascriptnodejs) JavaScript client library: ```js const Influx = require('influx') // Instantiate a client for writing to InfluxDB Clustered v1 API const client = new Influx.InfluxDB({ host: 'cluster-host.com', port: 443, protocol: 'https' database: 'DATABASE_NAME', username: 'ignored', password: 'DATABASE_TOKEN' }) ``` Create a v1 API client using the [influxdb-python](/influxdb/v1/tools/api_client_libraries/#python) Python client library: ```py from influxdb import InfluxDBClient # Instantiate a client for writing to InfluxDB Clustered v1 API client = InfluxDBClient( host='cluster-host.com', ssl=True, database='DATABASE_NAME', username='', password='DATABASE_TOKEN' headers={'Content-Type': 'text/plain; charset=utf-8'} ) ``` Replace the following: * `DATABASE_NAME`: your InfluxDB Clustered [database](/influxdb3/clustered/admin/databases/) * `DATABASE_TOKEN`: a [database token](/influxdb3/clustered/admin/tokens/#database-tokens) with sufficient permissions to the specified database ## Query data InfluxDB Clustered provides the following protocols for executing a query: * [Flight+gRPC](https://arrow.apache.org/docs/format/Flight.html) request that contains an SQL or InfluxQL query. To learn how to query InfluxDB Clustered using Flight and SQL, see the [Get started](/influxdb3/clustered/get-started/) tutorial. * InfluxDB v1 API `/query` request that contains an InfluxQL query. Use this endpoint with InfluxDB Clustered when you bring InfluxDB 1.x workloads that already use [InfluxQL](/influxdb3/clustered/reference/glossary/#influxql) and the v1 API `/query` endpoint. #### Tools to execute queries InfluxDB Clustered supports many different tools for querying data, including: * [`influx3` data CLI](https://github.com/InfluxCommunity/influxdb3-python-cli) * [InfluxDB 3 client libraries](/influxdb3/clustered/reference/client-libraries/v3/) * [Flight clients](/influxdb3/clustered/reference/client-libraries/flight/) * [Superset](/influxdb3/clustered/query-data/sql/execute-queries/superset/) * [Grafana](/influxdb3/clustered/query-data/sql/execute-queries/grafana/) * [InfluxQL with InfluxDB v1 HTTP API](/influxdb3/clustered/query-data/execute-queries/influxdb-v1-api/) * [Chronograf](/chronograf/v1/) ### v1 API /query parameters For InfluxDB Clustered v1 API `/query` requests, set parameters as listed in the following table: | Parameter | Allowed in | Ignored | Value | |--------------|------------|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `chunked` |Query string| Honored | Returns points in streamed batches instead of in a single response. If set to `true`, InfluxDB chunks responses by series or by every 10,000 points, whichever occurs first. | |`chunked_size`|Query string| Honored | **Requires `chunked` to be set to `true`**. If set to a specific value, InfluxDB chunks responses by series or by this number of points. | | `db` |Query string| Honored | Database name | | `epoch` |Query string| Honored | [Timestamp precision](#timestamp-precision) | | `p` |Query string| Honored | Database token | | `pretty` |Query string| Ignored | N/A | | `u` |Query string| Ignored | For [query string authentication](#query-string-authentication), any arbitrary string | | `p` |Query string| Honored |For [query string authentication](#query-string-authentication), a [database token](/influxdb3/clustered/get-started/setup/#create-a-database-token) with permission to write to the database| | `rp` |Query string|Honored, but discouraged| Retention policy | > [!Note] > When bringing v1 API workloads to InfluxDB Clustered, you’ll need to adjust request parameters in your client configuration or code. #### Timestamp precision Use one of the following values for timestamp precision: * `ns`: nanoseconds * `us`: microseconds * `ms`: milliseconds * `s`: seconds * `m`: minutes * `h`: hours ### Database management with InfluxQL (not supported) InfluxDB Clustered doesn’t allow InfluxQL commands for managing or modifying databases. You can’t use the following InfluxQL commands: ```sql SELECT INTO CREATE DELETE DROP GRANT EXPLAIN REVOKE ALTER SET KILL ``` #### Related * [Query data with SQL](/influxdb3/clustered/query-data/sql/) * [Query data with InfluxQL](/influxdb3/clustered/query-data/influxql/) * [Write data to InfluxDB Clustered](/influxdb3/clustered/write-data/) * [Configure Telegraf for InfluxDB](/influxdb3/clustered/write-data/use-telegraf/configure/) * [InfluxDB API client libraries](/influxdb3/clustered/reference/client-libraries/) [write](/influxdb3/clustered/tags/write/)[line protocol](/influxdb3/clustered/tags/line-protocol/) | Parameter | Allowed in | Ignored | Value | | --- | --- | --- | --- | | Parameter | Allowed in | Ignored | Value | | consistency | Query string | Ignored | N/A | | db * | Query string | Honored | Database name | | precision | Query string | Honored | Timestamp precision | | rp | Query string | Honored, but discouraged | Retention policy | | u | Query string | Ignored | For query string authentication , any arbitrary string | | p | Query string | Honored | For query string authentication , a database token with permission to write to the database | | Content-Encoding | Header | Honored | gzip (compressed data) or identity (uncompressed) | | Authorization | Header | Honored | Bearer DATABASE_TOKEN , Token DATABASE_TOKEN , or Basic | | Parameter | Ignored | Value | | --- | --- | --- | | Parameter | Ignored | Value | | database | Honored | Database name | | retention_policy | Honored, but discouraged | Duration | | username | Ignored | String or empty | | password | Honored | database token with permission to write to the database | | content_encoding | Honored | gzip (compressed data) or identity (uncompressed) | | skip_database_creation | Ignored | N/A (see how to create a database ) | | Parameter | Allowed in | Ignored | Value | | --- | --- | --- | --- | | Parameter | Allowed in | Ignored | Value | | chunked | Query string | Honored | Returns points in streamed batches instead of in a single response. If set to true , InfluxDB chunks responses by series or by every 10,000 points, whichever occurs first. | | chunked_size | Query string | Honored | Requires chunked to be set to true . If set to a specific value, InfluxDB chunks responses by series or by this number of points. | | db | Query string | Honored | Database name | | epoch | Query string | Honored | Timestamp precision | | p | Query string | Honored | Database token | | pretty | Query string | Ignored | N/A | | u | Query string | Ignored | For query string authentication , any arbitrary string | | p | Query string | Honored | For query string authentication , a database token with permission to write to the database | | rp | Query string | Honored, but discouraged | Retention policy |