Use the InfluxDB v1 API with InfluxDB Cloud Dedicated
Use the InfluxDB v1 API with v1 workloads that you bring to InfluxDB Cloud Dedicated.
InfluxDB Cloud Dedicated v1 /write
and /query
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.
The InfluxDB v1 API /query
endpoint supports InfluxQL and third-party integrations like Grafana.
For new workloads, use the following:
- The InfluxDB v2 API
/api/v2/write
endpoint for writing data. - A Flight SQL client and SQL for querying data.
Authenticate API requests
InfluxDB requires each write request to be authenticated with a
database token.
With the InfluxDB v1 API, 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.
In the InfluxDB Cloud Dedicated HTTP API, Authorization: Bearer
and Authorization: Token
are equivalent.
Authenticate with a username and password scheme
With the InfluxDB v1 API, you can use the InfluxDB 1.x convention of
username and password to authenticate database reads and writes by passing a
database token
as the password
credential.
When authenticating requests to the v1 API /write
and /query
endpoints, InfluxDB Cloud Dedicated checks that password
(p
) is an authorized database token.
InfluxDB Cloud 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):
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.
InfluxDB Cloud Dedicated ignores the username
part of the decoded credential.
Syntax
Authorization: Basic <base64-encoded [USERNAME]:DATABASE_TOKEN>
Replace the following:
[USERNAME]
: an optional string value (ignored by InfluxDB Cloud Dedicated).DATABASE_TOKEN
: a database token.- Encode the
[USERNAME]:DATABASE_TOKEN
credential using base64 encoding, and then append the encoded string to theAuthorization: Basic
header.
Most HTTP clients provide a Basic authentication option that
accepts the <username>:<password>
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:
#######################################
# Use Basic authentication with a database token
# to query the InfluxDB v1 API
#######################################
# Use the --user option with `--user username:DATABASE_TOKEN` syntax
#######################################
curl --get "http://cluster-id.influxdb.io/query" \
--user "":"DATABASE_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM MEASUREMENT"
Replace the following:
DATABASE_NAME
: your InfluxDB Cloud Dedicated databaseDATABASE_TOKEN
: a database token with sufficient permissions to the 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 p
(password) is an authorized database token and ignores the u
(username) parameter.
Syntax
https://cluster-id.influxdb.io/query/?[u=any]&p=DATABASE_TOKEN
https://cluster-id.influxdb.io/write/?[u=any]&p=DATABASE_TOKEN
Example
The following example shows how to use cURL with query string authentication and database token.
#######################################
# 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.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 databaseDATABASE_TOKEN
: a database token with sufficient permissions to the database
Authenticate with a token scheme
Use the Authorization: Bearer
or the Authorization: Token
scheme to pass a database token 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.
Support for one or the other may vary across InfluxDB API clients.
Syntax
Authorization: Bearer DATABASE_TOKEN
Authorization: Token DATABASE_TOKEN
Examples
Use Bearer
to authenticate a write request:
########################################################
# Use the Bearer authorization scheme with v1 /write
# to write data.
########################################################
curl -i "https://cluster-id.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:
########################################################
# Use the Bearer authorization scheme with v1 /write
# to write data.
########################################################
curl -i "https://cluster-id.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 databaseDATABASE_TOKEN
: a database token with sufficient permissions to the 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 Cloud Dedicated 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 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.
Write data with the v1 API
Write data with your existing workloads that already use the InfluxDB v1 API or v1.x-compatibility API.
See how to set parameters and configure the following tools for writing to InfluxDB Cloud Dedicated:
Write using Telegraf
If you have existing v1 workloads that use Telegraf,
you can use the InfluxDB v1.x influxdb
Telegraf output plugin to write data.
Use Telegraf and the v2 API for new workloads that don’t use already use the v1 API.
The following table shows outputs.influxdb
parameters and values writing
to InfluxDB Cloud Dedicated:
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:
[[outputs.influxdb]]
urls = ["https://cluster-id.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 databaseDATABASE_TOKEN
: a database token with permission to write to the database
Other Telegraf configuration options
influx_uint_support
: supported in InfluxDB IOx.
For more plugin options, see influxdb
on GitHub.
Write using client libraries
Use language-specific v1 client libraries and your custom code to write data to InfluxDB Cloud Dedicated.
v1 client libraries send data in 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:
Create a v1 API client using the node-influx JavaScript client library:
const Influx = require('influx')
// Instantiate a client for writing to InfluxDB Cloud Dedicated v1 API
const client = new Influx.InfluxDB({
host: 'cluster-id.influxdb.io',
port: 443,
protocol: 'https'
database: 'DATABASE_NAME',
username: 'ignored',
password: 'DATABASE_TOKEN'
})
Create a v1 API client using the influxdb-python Python client library:
from influxdb import InfluxDBClient
# Instantiate a client for writing to InfluxDB Cloud Dedicated v1 API
client = InfluxDBClient(
host='cluster-id.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 databaseDATABASE_TOKEN
: a database token with sufficient permissions to the database
Write using HTTP clients
Use HTTP clients and your custom code to send write requests to the v1 API /write
endpoint.
POST https://cluster-id.influxdb.io/write
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 syntax.
- A database token in one of the following authentication schemes: Basic authentication, query string authentication, or token authentication.
- Optional parameters.
v1 API /write parameters
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 <base64 [USERNAME]:DATABASE_TOKEN> |
Timestamp precision
Use one of the following precision
values in v1 API /write
requests:
ns
: nanosecondsus
: microsecondsms
: millisecondss
: secondsm
: minutesh
: hours
Use clients for interactive testing
To test interactively, use common HTTP clients such as cURL and Postman to send requests to the v1 API /write
endpoint.
While the v1 CLI may coincidentally work with InfluxDB Cloud Dedicated, it isn’t officially supported.
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:
curl -i 'https://cluster-id.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 1463683075'
Replace the following:
DATABASE_NAME
: your InfluxDB Cloud Dedicated databaseDATABASE_TOKEN
: a database token with sufficient permissions to the 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.
If you need to test writes interactively, see how to write using HTTP clients.
Query data
Query using the v1 API
Use the v1 API /query
endpoint and InfluxQL with InfluxDB Cloud Dedicated when you
bring InfluxDB 1.x workloads that already use them.
InfluxDB Cloud Dedicated
For new workloads, see how to query using Flight SQL.
v1 API /query parameters
Parameter | Allowed in | Ignored | Value |
---|---|---|---|
chunked | Ignored | N/A (Note that an unbounded query might return a large amount of data) | |
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 |
Timestamp precision
Use one of the following values for timestamp precision:
ns
: nanosecondsus
: microsecondsms
: millisecondss
: secondsm
: minutesh
: hours
Query using HTTP clients
Use HTTP clients and your custom code to send InfluxQL queries to the v1 API /query
endpoint.
GET https://cluster-id.influxdb.io/query
Include the following in your request:
- A
db
query string parameter with the name of the database to write to. - A database token in one of the following authentication schemes: Basic authentication, query string authentication, or token authentication.
- A
q
query string parameter with the InfluxQL query. - Optional parameters.
The following examples show how to query using the v1 API /query
endpoint and InfluxQL:
########################################################
# Use Token authentication with a database token
# to query the InfluxDB v1 API
########################################################
curl --get "https://cluster-id.influxdb.io/query" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--header 'Content-type: application/json' \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SHOW MEASUREMENTS"
########################################################
# Use Token authentication with a database token
# to query the InfluxDB v1 API
########################################################
curl --get "https://cluster-id.influxdb.io/query" \
--header "Authorization: Token DATABASE_TOKEN" \
--header 'Content-type: application/json' \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM MEASUREMENT"
from influxdb import InfluxDBClient
import os
DATABASE_NAME = os.getenv('CLOUD_DEDICATED_DATABASE_NAME')
DATABASE_TOKEN = os.getenv('CLOUD_DEDICATED_DATABASE_TOKEN')
INFLUXDB_URL=os.getenv('CLOUD_DEDICATED_URL')
INFLUXDB_HOST=os.getenv('CLOUD_DEDICATED_HOST')
def influxdb_v1_client(headers=None):
client = InfluxDBClient(
host=INFLUXDB_HOST,
port=443,
ssl=True,
database=DATABASE_NAME,
username='USERNAME',
password=DATABASE_TOKEN,
headers=headers
)
print(vars(client))
return client
def query_influxql():
client = influxdb_v1_client()
response = client.query('SHOW MEASUREMENTS')
print(response)
return response
The response body contains query results in JSON format.
Query using Flight SQL
Use Flight SQL clients with gRPC and SQL to query data stored in an InfluxDB Cloud Dedicated database.
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:
SELECT INTO
CREATE
DELETE
DROP
GRANT
EXPLAIN
REVOKE
ALTER
SET
KILL
Was this page helpful?
Thank you for your feedback!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB and this documentation. To find support, use the following resources:
InfluxDB Cloud and InfluxDB Enterprise customers can contact InfluxData Support.