Documentation

InfluxDB Cloud Serverless

Use the InfluxDB v1 API

Use the InfluxDB v1 API /write and /query endpoints with v1 workloads that you bring to InfluxDB Cloud Serverless. 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. The InfluxDB v1 API /query endpoint supports InfluxQL and third-party integrations like Grafana.

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 Serverless database.

Authenticate API requests

InfluxDB Cloud Serverless requires each API request to be authenticated with an API token. With the InfluxDB v1 API, you can use API tokens in InfluxDB 1.x username and password schemes or in the InfluxDB v2 Authorization: Token scheme.

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 bucket reads and writes by passing an API token as the password credential. When authenticating requests to the v1 API /write and /query endpoints, InfluxDB Cloud Serverless checks that the password (p) value is an authorized API token. InfluxDB Cloud Serverless 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 Serverless checks that the password part of the decoded credential is an authorized API token. InfluxDB Cloud Serverless ignores the username part of the decoded credential.

Syntax
Authorization: Basic <base64-encoded [USERNAME]:API_TOKEN>

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 <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 an API token:

#######################################
# Use Basic authentication with a database token
# to query the InfluxDB v1 API
#######################################


curl --get "https://cloud2.influxdata.com/query" \
  --user "":"
API_TOKEN
" \
  --data-urlencode "db=
BUCKET_NAME
" \
  --data-urlencode "rp=
RETENTION_POLICY
" \
  --data-urlencode "q=SELECT * FROM MEASUREMENT"

Replace the following:

  • BUCKET_NAME: your InfluxDB Cloud Serverless bucket
  • RETENTION_POLICY: your InfluxDB Cloud Serverless retention policy
  • API_TOKEN: an API token with sufficient permissions to the bucket

Query string authentication

In the URL, pass the p query parameter to authenticate /write and /query requests. When authenticating requests, InfluxDB Cloud Serverless checks that the p (password) value is an authorized API token and ignores the u (username) parameter.

Syntax
https://cloud2.influxdata.com/query/?[u=any]&p=API_TOKEN
https://cloud2.influxdata.com/write/?[u=any]&p=API_TOKEN
Example

The following example shows how to use cURL with query string authentication and API token.

#######################################
# Use an InfluxDB 1.x compatible username and password
# to query the InfluxDB v1 API
#######################################

curl --get "https://cloud2.influxdata.com/query" \
  --data-urlencode "p=
API_TOKEN
" \
  --data-urlencode "db=
BUCKET_NAME
" \
  --data-urlencode "rp=
RETENTION_POLICY
" \
  --data-urlencode "q=SELECT * FROM MEASUREMENT"

Replace the following:

  • BUCKET_NAME: your InfluxDB Cloud Serverless bucket
  • RETENTION_POLICY: your InfluxDB Cloud Serverless retention policy
  • API_TOKEN: an API token with sufficient permissions to the bucket

Authenticate with a token scheme

Use the Authorization: Token scheme to pass an API token for authenticating v1 API /write and /query requests.

Syntax

Authorization: Token API_TOKEN

Examples

Use Token to authenticate a write request:

########################################################
# Use the Token authorization scheme with v1 /write
# to write data.
########################################################

curl -i "https://cloud2.influxdata.com/write?db=
BUCKET_NAME
&rp=
RETENTION_POLICY
&precision=ms" \
    --header "Authorization: Token 
API_TOKEN
" \
    --header "Content-type: text/plain; charset=utf-8" \
    --data-binary 'home,room=kitchen temp=72 1682358973500'

Replace the following:

  • BUCKET_NAME: your InfluxDB Cloud Serverless bucket
  • RETENTION_POLICY: your InfluxDB Cloud Serverless retention policy
  • API_TOKEN: an API token with sufficient permissions to the bucket

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 Serverless 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 bucket 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

Write data with your existing workloads that already use the InfluxDB v1 or v1.x-compatibility /write API endpoint.

POST https://cloud2.influxdata.com/write

v1 API /write parameters

For InfluxDB Cloud Serverless v1 API /write requests, set parameters as listed in the following table:

ParameterAllowed inIgnoredValue
consistencyQuery stringIgnoredN/A
db *Query stringHonoredBucket name
precisionQuery stringHonoredTimestamp precision
rp *Query stringHonoredRetention policy
uQuery stringIgnoredFor query string authentication, any arbitrary string
pQuery stringHonoredFor query string authentication, an API token with permission to write to the bucket
Content-EncodingHeaderHonoredgzip (compressed data) or identity (uncompressed)
AuthorizationHeaderHonoredToken API_TOKEN, or Basic <base64 [USERNAME]:API_TOKEN>
* = 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 Serverless /write endpoint:

Telegraf

If you have existing v1 workloads that use Telegraf, you can use the InfluxDB v1.x influxdb Telegraf output plugin to write data.

See how to use Telegraf and the v2 API 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 Serverless v1 API:

ParameterIgnoredValue
databaseHonoredBucket name
retention_policyHonoredDuration
usernameIgnoredString or empty
passwordHonoredAPI token with permission to write to the bucket
content_encodingHonoredgzip (compressed data) or identity (uncompressed)
skip_database_creationIgnoredN/A (see how to create a bucket)

To configure the v1.x output plugin for writing to InfluxDB Cloud Serverless, add the following outputs.influxdb configuration in your telegraf.conf file:

[[outputs.influxdb]]
  urls = ["https://cloud2.influxdata.com"]
  database = "
BUCKET_NAME
"
  skip_database_creation = true
  retention_policy = "
RETENTION_POLICY
"
  username = "ignored"
  password = "
API_TOKEN
"
  content_encoding = "gzip”

Replace the following:

  • BUCKET_NAME: your InfluxDB Cloud Serverless bucket
  • RETENTION_POLICY: your InfluxDB Cloud Serverless retention policy
  • API_TOKEN: an API token with sufficient permissions to the bucket
Other Telegraf configuration options

influx_uint_support: supported in InfluxDB IOx.

For more plugin options, see 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:

The following example shows how to use the cURL command line tool and the InfluxDB Cloud Serverless v1 API to write line protocol data to a bucket:

curl -i 'https://cloud2.influxdata.com/write?db=
BUCKET_NAME
&rp=
RETENTION_POLICY
&precision=s' \
    --header 'Authorization: Token 
API_TOKEN
' \
    --header "Content-type: text/plain; charset=utf-8"
    --data-binary 'home,room=kitchen temp=72 1463683075'

Replace the following:

  • BUCKET_NAME: your InfluxDB Cloud Serverless bucket
  • RETENTION_POLICY: your InfluxDB Cloud Serverless retention policy
  • API_TOKEN: an API token with sufficient permissions to the bucket
v1 CLI (not supported)

Don’t use the v1 CLI with InfluxDB Cloud Serverless. While it may coincidentally work, it isn’t officially supported.

Client libraries

Use language-specific v1 client libraries and your custom code to write data to InfluxDB. 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 Serverless:

Node.js Python

Create a v1 API client using the node-influx JavaScript client library:

const Influx = require('influx')

// Instantiate a client for writing to InfluxDB Cloud Serverless v1 API
const client = new Influx.InfluxDB({
  host: 'cloud2.influxdata.com',
  port: 443,
  protocol: 'https'
  database: '
BUCKET_NAME
',
  username: 'ignored',
  password: '
API_TOKEN
'
})

// When calling write or query functions, specify the retention policy name in options.

Create a v1 API client using the influxdb-python Python client library:

from influxdb import InfluxDBClient

# Instantiate a client for writing to InfluxDB Cloud Serverless v1 API
client = InfluxDBClient(
  host='cloud2.influxdata.com',
  ssl=True,
  database='
BUCKET_NAME
',
  username='',
  password='
API_TOKEN
'
  headers={'Content-Type': 'text/plain; charset=utf-8'}
  )

# When calling write or query functions, specify the retention policy name in options.

Replace the following:

  • BUCKET_NAME: your InfluxDB Cloud Serverless bucket
  • RETENTION_POLICY: your InfluxDB Cloud Serverless retention policy
  • API_TOKEN: an API token with sufficient permissions to the bucket

Query data

InfluxDB Cloud Serverless provides the following protocols for executing a query:

  • Flight+gRPC request that contains an SQL or InfluxQL query. To learn how to query InfluxDB Cloud Serverless using Flight and SQL, see the Get started tutorial.
  • InfluxDB v1 API /query request that contains an InfluxQL query. Use this endpoint with InfluxDB Cloud Serverless when you bring InfluxDB 1.x workloads that already use InfluxQL and the v1 API /query endpoint.

Tools to execute queries

InfluxDB Cloud Serverless supports many different tools for querying data, including:

v1 API /query parameters

For InfluxDB Cloud Serverless v1 API /query requests, set parameters as listed in the following table:

ParameterAllowed inIgnoredValue
chunkedIgnoredN/A (Note that an unbounded query might return a large amount of data)
dbQuery stringHonoredBucket name
epochQuery stringHonoredTimestamp precision
prettyQuery stringIgnoredN/A
uQuery stringIgnoredFor query string authentication, any arbitrary string
pQuery stringHonoredFor query string authentication, an API token with permission to write to the bucket
rpQuery stringHonoredRetention policy

When bringing v1 API workloads to InfluxDB Cloud Serverless, 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

Bucket management with InfluxQL (not supported)

InfluxDB Cloud Serverless doesn’t allow InfluxQL commands for managing or modifying buckets. You can’t use the following InfluxQL commands:

SELECT INTO
CREATE
DELETE
DROP
GRANT
EXPLAIN
REVOKE
ALTER
SET
KILL
write line protocol

Was this page helpful?

Thank you for your feedback!

© 2023 InfluxData, Inc.

Select your InfluxDB Cloud region

Select your InfluxDB Cloud region and cluster and we’ll customize code examples for you. Identify your InfluxDB Cloud cluster.

AWS

For more information, see InfluxDB Cloud Serverless regions.

Thank you for your feedback!

Let us know what we can do better:

Thank you!

No thanks

Introducing InfluxDB Clustered

A highly available InfluxDB 3.0 cluster on your own infrastructure.

InfluxDB Clustered is a highly available InfluxDB 3.0 cluster built for high write and query workloads on your own infrastructure.

InfluxDB Clustered is currently in limited availability and is only available to a limited group of InfluxData customers. If interested in being part of the limited access group, please contact the InfluxData Sales team.

Learn more
Contact InfluxData Sales

The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Flux is going into maintenance mode and will not be supported in InfluxDB 3.0. This was a decision based on the broad demand for SQL and the continued growth and adoption of InfluxQL. We are continuing to support Flux for users in 1.x and 2.x so you can continue using it with no changes to your code. If you are interested in transitioning to InfluxDB 3.0 and want to future-proof your code, we suggest using InfluxQL.

For information about the future of Flux, see the following:

State of the InfluxDB Cloud Serverless documentation

InfluxDB Cloud Serverless documentation is a work in progress.

The new documentation for InfluxDB Cloud Serverless is a work in progress. We are adding new information and content almost daily. Thank you for your patience!

If there is specific information you’re looking for, please submit a documentation issue.

InfluxDB Cloud Serverless

You are currently viewing documentation specific to InfluxDB Cloud Serverless powered by the IOx storage engine, which offers different functionality than InfluxDB Cloud powered by the TSM storage engine.

Are you using InfluxDB Cloud Serverless? How to find out?

Visit your organization's homepage and look for:

InfluxDB Cloud Serverless
Yes – I'm using InfluxDB Cloud Serverless No – I'm using InfluxDB Cloud (TSM)