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:
In your request, set the following:
- Your organization via the
org
ororgID
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)'
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)'
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:
In your request, set the following:
- 1.x-compatible or 2.x authentication credentials
- Headers:
Accept: application/csv
orAccept: 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"
# 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"
Replace the following with your values:
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"
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"
Replace the following with your values:
InfluxDB returns the query results in annotated CSV.
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:
Customers with an annual or support contract can contact InfluxData Support. Customers using a trial license can email trial@influxdata.com for assistance.