--- title: Use the InfluxDB v1 API with InfluxDB Cloud Dedicated description: Use InfluxDB v1 API authentication, endpoints, and tools when bringing existing 1.x workloads to InfluxDB Cloud Dedicated. url: https://docs.influxdata.com/influxdb3/cloud-dedicated/guides/api-compatibility/v1/ estimated_tokens: 10740 product: InfluxDB Cloud Dedicated version: cloud-dedicated --- # Use the InfluxDB v1 API with InfluxDB Cloud Dedicated Use the InfluxDB v1 API `/write` and `/query` endpoints with v1 workloads that you bring to InfluxDB Cloud Dedicated. 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 Cloud Dedicated 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 Cloud Dedicated requires each API request to be authenticated with a [database token](/influxdb3/cloud-dedicated/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/cloud-dedicated/admin/tokens/#database-tokens) as the `password` credential. When authenticating requests to the v1 API `/write` and `/query` endpoints, InfluxDB Cloud Dedicated checks that the `password` (`p`) value is an authorized [database token](/influxdb3/cloud-dedicated/admin/tokens/#database-tokens). InfluxDB Cloud Dedicated 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 Cloud Dedicated checks that the `password` part of the decoded credential is an authorized [database token](/influxdb3/cloud-dedicated/admin/tokens/#database-tokens). InfluxDB Cloud Dedicated 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. 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/cloud-dedicated/admin/tokens/#database-tokens): ```sh ####################################### # Use Basic authentication with a database token # to query the InfluxDB v1 API ####################################### curl --get "https://cluster-id.a.influxdb.io/query" \ --user "any:DATABASE_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM MEASUREMENT" ``` Replace the following: - `DATABASE_NAME`: your InfluxDB Cloud Dedicated database - `DATABASE_TOKEN`: a [database token](/influxdb3/cloud-dedicated/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 Cloud Dedicated checks that the `p` (*password*) value is an authorized database token and ignores the `u` (*username*) parameter. ##### Syntax ```http https://cluster-id.a.influxdb.io/query/?[u=any]&p=DATABASE_TOKEN https://cluster-id.a.influxdb.io/write/?[u=any]&p=DATABASE_TOKEN ``` ##### Example The following example shows how to use cURL with query string authentication and [database token](/influxdb3/cloud-dedicated/admin/tokens/#database-tokens). ```sh ####################################### # Use an InfluxDB 1.x compatible username and password # to query the InfluxDB v1 API ####################################### # Use authentication query parameters: # ?p=DATABASE_TOKEN ####################################### curl --get "https://cluster-id.a.influxdb.io/query" \ --data-urlencode "p=DATABASE_TOKEN" \ --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SELECT * FROM MEASUREMENT" ``` Replace the following: - `DATABASE_NAME`: your InfluxDB Cloud Dedicated database - `DATABASE_TOKEN`: a [database token](/influxdb3/cloud-dedicated/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/cloud-dedicated/admin/tokens/#database-tokens) for authenticating v1 API `/write` and `/query` requests. `Bearer` and `Token` are equivalent in InfluxDB Cloud Dedicated. 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 ######################################################## # Use the Bearer authorization scheme with v1 /write # to write data. ######################################################## curl -i "https://cluster-id.a.influxdb.io/write?db=DATABASE_NAME&precision=ms" \ --header "Authorization: Bearer DATABASE_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1682358973500' ``` Use `Token` to authenticate a write request: ```sh ######################################################## # Use the Token authorization scheme with v1 /write # to write data. ######################################################## curl -i "https://cluster-id.a.influxdb.io/write?db=DATABASE_NAME&precision=ms" \ --header "Authorization: Token DATABASE_TOKEN" \ --header "Content-type: text/plain; charset=utf-8" \ --data-binary 'home,room=kitchen temp=72 1682358973500' ``` Replace the following: - `DATABASE_NAME`: your InfluxDB Cloud Dedicated database - `DATABASE_TOKEN`: a [database token](/influxdb3/cloud-dedicated/admin/tokens/#database-tokens) with sufficient permissions to the specified database ## Responses InfluxDB HTTP API responses use standard [HTTP status codes](/influxdb3/cloud-dedicated/api/data-api/response-codes/). The response body for [partial writes](/influxdb3/cloud-dedicated/write-data/troubleshoot/#troubleshoot-rejected-points) and errors contains a JSON object with `code` and `message` properties that describe the error. Response body messages may differ across InfluxDB Cloud Dedicated v1 API, v2 API, InfluxDB Cloud, and InfluxDB OSS. ### Error examples - **Invalid namespace name**: ```http 400 Bad Request ``` ```json { "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/cloud-dedicated/admin/databases/) name. - **Failed to deserialize db/rp/precision** ```http 400 Bad Request ``` ```json { "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-id.a.influxdb.io/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 Cloud Dedicated 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 | | 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 | \* = 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 Cloud Dedicated `/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. See how to [use Telegraf and the v2 API](/influxdb3/cloud-dedicated/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 Cloud Dedicated v1 API: | 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) | To configure the v1.x output plugin for writing to InfluxDB Cloud Dedicated, add the following `outputs.influxdb` configuration in your `telegraf.conf` file: ```toml [[outputs.influxdb]] urls = ["https://cluster-id.a.influxdb.io"] database = "DATABASE_NAME" skip_database_creation = true retention_policy = "" username = "ignored" password = "DATABASE_TOKEN" content_encoding = "gzip" ``` Replace the following: - `DATABASE_NAME`: your InfluxDB Cloud Dedicated database - `DATABASE_TOKEN`: a [database token](/influxdb3/cloud-dedicated/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/cloud-dedicated/reference/syntax/line-protocol/) syntax. - A [database token](/influxdb3/cloud-dedicated/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 Cloud Dedicated v1 API to write line protocol data to a database: ```sh curl -i 'https://cluster-id.a.influxdb.io/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 Cloud Dedicated database - `DATABASE_TOKEN`: a [database token](/influxdb3/cloud-dedicated/admin/tokens/#database-tokens) with sufficient permissions to the specified database ##### v1 CLI (not supported) Don’t use the v1 CLI with InfluxDB Cloud Dedicated. 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/cloud-dedicated/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 Cloud Dedicated: **Node.js:** 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 Cloud Dedicated v1 API const client = new Influx.InfluxDB({ host: 'cluster-id.a.influxdb.io', port: 443, protocol: 'https' database: 'DATABASE_NAME', username: 'ignored', password: 'DATABASE_TOKEN' }) ``` **Python:** 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 Cloud Dedicated v1 API client = InfluxDBClient( host='cluster-id.a.influxdb.io', ssl=True, database='DATABASE_NAME', username='', password='DATABASE_TOKEN' headers={'Content-Type': 'text/plain; charset=utf-8'} ) ``` Replace the following: - `DATABASE_NAME`: your InfluxDB Cloud Dedicated database - `DATABASE_TOKEN`: a [database token](/influxdb3/cloud-dedicated/admin/tokens/#database-tokens) with sufficient permissions to the specified database ## Query data InfluxDB Cloud Dedicated 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 Cloud Dedicated using Flight and SQL, see the [Get started](/influxdb3/cloud-dedicated/get-started/) tutorial. - InfluxDB v1 API `/query` request that contains an InfluxQL query. Use this endpoint with InfluxDB Cloud Dedicated when you bring InfluxDB 1.x workloads that already use [InfluxQL](/influxdb3/cloud-dedicated/reference/glossary/#influxql) and the v1 API `/query` endpoint. #### Tools to execute queries InfluxDB Cloud Dedicated supports many different tools for querying data, including: - [`influx3` data CLI](https://github.com/InfluxCommunity/influxdb3-python-cli) - [InfluxDB 3 client libraries](/influxdb3/cloud-dedicated/reference/client-libraries/v3/) - [Flight clients](/influxdb3/cloud-dedicated/reference/client-libraries/flight/) - [Superset](/influxdb3/cloud-dedicated/query-data/sql/execute-queries/superset/) - [Grafana](/influxdb3/cloud-dedicated/query-data/sql/execute-queries/grafana/) - [InfluxQL with InfluxDB v1 HTTP API](/influxdb3/cloud-dedicated/query-data/execute-queries/influxdb-v1-api/) - [Chronograf](/chronograf/v1/) ### v1 API /query parameters For InfluxDB Cloud Dedicated 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 | | 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 | When bringing v1 API workloads to InfluxDB Cloud Dedicated, 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 Cloud Dedicated 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/cloud-dedicated/query-data/sql/) - [Query data with InfluxQL](/influxdb3/cloud-dedicated/query-data/influxql/) - [Write data to InfluxDB Cloud Dedicated](/influxdb3/cloud-dedicated/write-data/) - [Configure Telegraf for InfluxDB](/influxdb3/cloud-dedicated/write-data/use-telegraf/configure/) - [InfluxDB API client libraries](/influxdb3/cloud-dedicated/reference/client-libraries/)