Use the InfluxDB v2 API with InfluxDB Cloud Dedicated

Use the InfluxDB v2 API for new workloads and existing v2 workloads that you bring to InfluxDB Cloud Dedicated. The InfluxDB Cloud Dedicated v2 /api/v2/write endpoint works with token authentication and existing InfluxDB 2.x tools and code. For help finding the best workflow for your situation, contact Support.

• Authenticate API requests
  • Authenticate with a token
    • Syntax
    • Examples
• Responses
  • Error examples
• Write data
  • Write using Telegraf
    • Other Telegraf configuration options
  • Write using client libraries
  • Write using HTTP clients
    • v2 API /api/v2/write parameters
    • Timestamp precision
    • Use clients for interactive testing
  • influx CLI not supported
• Query data
  • Query using Flight SQL
  • /api/v2/query not supported

Authenticate API requests

InfluxDB requires each write request to be authenticated with a database token.

Authenticate with a token

Use the Authorization: Bearer scheme or the Authorization: Token scheme to pass a database token that has write permission to your database.

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 token authentication scheme with /api/v2/write
# to write data.
########################################################

curl --post "https://cluster-id.influxdb.io/api/v2/write?bucket=DATABASE_NAME&precision=s" \
  --header "Authorization: Bearer DATABASE_TOKEN" \
  --data-binary 'home,room=kitchen temp=72 1463683075'

Use Token to authenticate a write request:

########################################################
# Use the Token authentication scheme with /api/v2/write
# to write data.
########################################################

curl --post "https://cluster-id.influxdb.io/api/v2/write?bucket=DATABASE_NAME&precision=s" \
  --header "Authorization: Token DATABASE_TOKEN" \
  --data-binary 'home,room=kitchen temp=72 1463683075'

Replace the following:

• DATABASE_NAME: your InfluxDB Cloud Dedicated database
• DATABASE_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

• Missing bucket value

  400 Bad Request
  

  HTTP response body: {"code":"invalid","message":"missing bucket value"}
  

  The ?bucket= parameter value is missing in the request. Provide the database name.

• Failed to deserialize org/bucket/precision

  400 Bad Request
  

  {"code":"invalid","message":"failed to deserialize org/bucket/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

Use the InfluxDB Cloud Dedicated v2 API /api/v2/write endpoint to write data to a database. We recommend using the v2 API /api/v2/write endpoint for new and existing workloads.

See how to set parameters and configure the following tools for writing to InfluxDB Cloud Dedicated:

• Write using Telegraf
• Write using client libraries
• Write using HTTP clients
  • v2 API /api/v2/write parameters
  • Use clients for interactive testing

Write using Telegraf

Use the InfluxDB v2.x influxdb_v2 Telegraf output plugin to write data.

The following table shows outputs.influxdb parameters and values for writing to InfluxDB Cloud Dedicated:

To configure the v2.x output plugin for writing to InfluxDB Cloud Dedicated, add the following outputs.influxdb_v2 configuration in your telegraf.conf file:

[[outputs.influxdb_v2]]
 urls = ["https://cluster-id.influxdb.io"]
 token = "DATABASE_TOKEN"
 organization = ""
 bucket = "DATABASE_NAME"
 content_encoding = "gzip"
 influx_uint_support = false

Replace the following:

• DATABASE_NAME: your InfluxDB Cloud Dedicated database
• DATABASE_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_v2 on GitHub.

Write using client libraries

Use language-specific v2 client libraries and your custom code to write data to InfluxDB Cloud Dedicated. v2 client libraries send data in line protocol syntax to the v2 API /api/v2/write endpoint.

The following samples show how to configure v2 client libraries for writing to InfluxDB Cloud Dedicated:

influxdb_client = InfluxDBClient(url='https://cluster-id.influxdb.io',
                                token='DATABASE_TOKEN',
                                org='ignored')

    write_api = influxdb_client.write_api(write_options=SYNCHRONOUS)

Replace the following:

• DATABASE_NAME: your InfluxDB Cloud Dedicated database
• DATABASE_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 v2 API /api/v2/write endpoint.

POST https://cluster-id.influxdb.io/api/v2/write

Include the following in your request:

• A bucket 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 a token authentication scheme.
• Optional parameters.

v2 API /api/v2/write parameters

Timestamp precision

Use one of the following precision values in v2 API /api/v2/write requests:

• ns: nanoseconds
• us: microseconds
• ms: milliseconds
• s: seconds
• m: minutes
• h: hours

Use clients for interactive testing

To test interactively, use common HTTP clients such as cURL and Postman to send requests to the v2 API /api/v2/write endpoint.

The following example shows how to use the cURL command line tool and the InfluxDB Cloud Dedicated v2 API to write line protocol data to a database:

curl --request POST \
"https://cluster-id.influxdb.io/api/v2/write?bucket=DATABASE_NAME&precision=ns" \
  --header "Authorization: Bearer DATABASE_TOKEN" \
  --header "Content-Type: text/plain; charset=utf-8" \
  --header "Accept: application/json" \
  --data-binary '
    airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630424257000000000
    airSensors,sensor_id=TLM0202 temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826 1630424257000000000'

Replace the following:

• DATABASE_NAME: your InfluxDB Cloud Dedicated database
• DATABASE_TOKEN: a database token with sufficient permissions to the database

influx CLI not supported

Don’t use the influx 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

Use Flight SQL clients with gRPC and SQL to query data stored in an InfluxDB Cloud Dedicated database.

Query using Flight SQL

Choose from the following tools to query InfluxDB Cloud Dedicated:

• Flight SQL plugin for Grafana
• Superset
• pyinflux3 module
• flightsql-dbapi

See how to get started querying with SQL

/api/v2/query not supported

The /api/v2/query and associated tooling aren’t supported in InfluxDB Cloud Dedicated. See how to query using Flight SQL.