Documentation

Query with the InfluxDB API

This page documents an earlier version of InfluxDB OSS. InfluxDB 3 Core is the latest stable version.

The InfluxDB v2 API provides a programmatic interface for all interactions with InfluxDB. To query InfluxDB 2.7, do one of the following:

Send a Flux query request

Send a Flux query request to the following endpoint:

POST /api/v2/query
  • Copy
  • Fill window

In your request, set the following:

  • Your organization via the org or orgID URL parameters
  • Headers:
    • Authorization: Token <API_TOKEN>
    • Accept: application/csv
    • Content-type: application/vnd.flux
  • Your Flux query text in the request body

Use gzip to compress a large query response

To compress the query response, set the Accept-Encoding header to gzip. This saves network bandwidth, but increases server-side load.

We recommend only using gzip compression on responses that are larger than 1.4 KB. If the response is smaller than 1.4 KB, gzip encoding will always return a 1.4 KB response, despite the uncompressed response size. 1500 bytes (~1.4 KB) is the maximum transmission unit (MTU) size for the public network and is the largest packet size allowed at the network layer.

Flux - Example query request

The following example shows how to use cURL to send a Flux query to InfluxDB 2.7:

curl \
  --request POST \
  http://localhost:8086/api/v2/query?orgID=
ORG_ID
\
--header 'Authorization: Token
API_TOKEN
'
\
--header 'Accept: application/csv' \ --header 'Content-type: application/vnd.flux' \ --data 'from(bucket:"
BUCKET_NAME
")
|> range(start: -12h) |> filter(fn: (r) => r._measurement == "example-measurement") |> aggregateWindow(every: 1h, fn: mean)'
  • Copy
  • Fill window
curl \
  --request POST \
  http://localhost:8086/api/v2/query?orgID=
ORG_ID
\
--header 'Authorization: Token
API_TOKEN
'
\
--header 'Accept: application/csv' \ --header 'Content-type: application/vnd.flux' \ --header 'Accept-Encoding: gzip' \ --data 'from(bucket:"
BUCKET_NAME
")
|> range(start: -12h) |> filter(fn: (r) => r._measurement == "example-measurement") |> aggregateWindow(every: 1h, fn: mean)'
  • Copy
  • Fill window

Replace the following with your values:

  • ORG_ID - the ID of the organization that owns the bucket.
  • API_TOKEN - your token.
  • BUCKET_NAME - the name of the bucket to query.

Send an InfluxQL query request

To query InfluxDB 2.7 using the InfluxQL query language, send a request to the v1-compatible API endpoint:

GET /query
  • Copy
  • Fill window
POST /query
  • Copy
  • Fill window

In your request, set the following:

  • 1.x-compatible or 2.x authentication credentials
  • Headers:
    • Accept: application/csv or Accept: application/json
    • Content-type: application/vnd.influxql
  • The database and retention policy mapped to the bucket you want to query
  • Your InfluxQL query text

If you have an existing bucket that doesn’t follow the database/retention-policy naming convention, you must manually create a database and retention policy mapping to query that bucket with the /query compatibility API. Use the db and rp query parameters to specify the database and retention policy for the bucket you want to query.

InfluxQL - Example query request

The following example shows how to use cURL to send an InfluxQL query to InfluxDB 2.7 using v1-compatible authentication:

# 1.x compatible POST request using Basic authentication and InfluxQL
curl --request POST \
  "http://localhost:8086/query?db=
BUCKET_NAME
&p=
API_TOKEN
&u=ignored"
\
--header "Content-type: application/vnd.influxql" \ --data "SELECT * FROM home WHERE time > now() - 1h"
  • Copy
  • Fill window
# 1.x compatible GET request using Basic authentication and InfluxQL
curl --get "http://localhost:8086/query" \
  --header "Accept: application/json" \
  --data-urlencode "q=SELECT * FROM home WHERE time > now() - 1h" \
  --data-urlencode "db=
BUCKET_NAME
"
\
--data-urlencode "u=ignored" \ --data-urlencode "p=
API_TOKEN
"
  • Copy
  • Fill window

Replace the following with your values:

  • API_TOKEN - your token.
  • BUCKET_NAME - the name of the bucket to query.
curl --get "http://localhost:8086/query" \
  --header 'Accept: application/csv' \
  --header 'Content-type: application/json' \
  --data-urlencode "db=
BUCKET_NAME
"
\
--data-urlencode "p=
API_TOKEN
"
\
--data-urlencode "u=ignored" \ --data-urlencode "q=SELECT used_percent FROM example-db.example-rp.example-measurement WHERE host=host1"
  • Copy
  • Fill window
curl --get "http://localhost:8086/query" \
  --header 'Accept: application/csv' \
  --header 'Content-type: application/json' \
  --header 'Accept-Encoding: gzip' \
  --data-urlencode "db=
BUCKET_NAME
"
\
--data-urlencode "p=
API_TOKEN
"
\
--data-urlencode "u=ignored" \ --data-urlencode "q=SELECT used_percent FROM example-db.example-rp.example-measurement WHERE host=host1"
  • Copy
  • Fill window

Replace the following with your values:

  • API_TOKEN - your token.
  • BUCKET_NAME - the name of the bucket to query.

InfluxDB returns the query results in annotated CSV.


Was this page helpful?

Thank you for your feedback!


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.

Read more

New in InfluxDB 3.2

Key enhancements in InfluxDB 3.2 and the InfluxDB 3 Explorer UI is now generally available.

See the Blog Post

InfluxDB 3.2 is now available for both Core and Enterprise, bringing the general availability of InfluxDB 3 Explorer, a new UI that simplifies how you query, explore, and visualize data. On top of that, InfluxDB 3.2 includes a wide range of performance improvements, feature updates, and bug fixes including automated data retention and more.

For more information, check out: