Query data

Download InfluxDB 3 Enterprise API Spec
Query data stored in InfluxDB 3 Enterprise using SQL or InfluxQL.
GET /api/v3/query_influxql

Execute InfluxQL query

Executes an InfluxQL query to retrieve data from the specified database.

With the performance upgrade preview enabled (--use-pacha-tree flag), queries automatically merge results from Parquet and .pt files (hybrid query mode).

Parameters

Query parameters
db string

The name of the database.

If you provide a query that specifies the database, you can omit the ‘db’ parameter from your request.

q required string
format string
params string
JSON-encoded query parameters for parameterized queries.
Header parameters
Accept string
The content type that the client can understand.
Allowed values: application/json , application/jsonl , application/vnd.apache.parquet , text/csv
Default: application/json
Example request Ask AI about this
curl --request GET \
  "https://localhost:8181/api/v3/query_influxql?q=Q" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains query results.
results object[]
Example request body
{
  "results": [
    {
      "series": [
        {
          "columns": [
            "time",
            "value"
          ],
          "name": "mytable",
          "values": [
            [
              "2024-02-02T12:00:00Z",
              42
            ]
          ]
        }
      ]
    }
  ]
}
400 Bad request.
401 Unauthorized access.
data object
error string
403 Access denied.
404 Database not found.
405 Method not allowed.
422 Unprocessable entity.
POST /api/v3/query_influxql

Execute InfluxQL query

Executes an InfluxQL query to retrieve data from the specified database.

With the performance upgrade preview enabled (--use-pacha-tree flag), queries automatically merge results from Parquet and .pt files (hybrid query mode).

Parameters

Header parameters
Accept string
The content type that the client can understand.
Allowed values: application/json , application/jsonl , application/vnd.apache.parquet , text/csv
Default: application/json
Content-Type string
The format of the data in the request body.
Allowed values: application/json

Request body

Content-Type: application/json
Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/api/v3/query_influxql" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"db":"mydb","format":"json","params":{},"q":"SELECT * FROM mytable"}'

Responses

200 Success. The response body contains query results.
results object[]
Example request body
{
  "results": [
    {
      "series": [
        {
          "columns": [
            "time",
            "value"
          ],
          "name": "mytable",
          "values": [
            [
              "2024-02-02T12:00:00Z",
              42
            ]
          ]
        }
      ]
    }
  ]
}
400 Bad request.
401 Unauthorized access.
data object
error string
403 Access denied.
404 Database not found.
405 Method not allowed.
422 Unprocessable entity.
GET /api/v3/query_sql

Execute SQL query

Executes an SQL query to retrieve data from the specified database.

With the performance upgrade preview enabled (--use-pacha-tree flag), queries automatically merge results from Parquet and .pt files (hybrid query mode). Use the /api/v3/query_sql_telemetry endpoint after executing a query to retrieve detailed execution statistics.

Parameters

Query parameters
db required string
The name of the database.
q required string <SQL>
The query to execute.
format string
params string
JSON-encoded query parameters for parameterized queries.
Header parameters
Accept string
The content type that the client can understand.
Allowed values: application/json , application/jsonl , application/vnd.apache.parquet , text/csv
Default: application/json
Content-Type string
The format of the data in the request body.
Allowed values: application/json
Example request Ask AI about this
curl --request GET \
  "https://localhost:8181/api/v3/query_sql?db=DB&q=Q" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains query results.
results object[]
Example request body
{
  "results": [
    {
      "series": [
        {
          "columns": [
            "time",
            "value"
          ],
          "name": "mytable",
          "values": [
            [
              "2024-02-02T12:00:00Z",
              42
            ]
          ]
        }
      ]
    }
  ]
}
400 Bad request.
401 Unauthorized access.
data object
error string
403 Access denied.
404 Database not found.
405 Method not allowed.
422 Unprocessable entity.
POST /api/v3/query_sql

Execute SQL query

Executes an SQL query to retrieve data from the specified database.

With the performance upgrade preview enabled (--use-pacha-tree flag), queries automatically merge results from Parquet and .pt files (hybrid query mode). Use the /api/v3/query_sql_telemetry endpoint after executing a query to retrieve detailed execution statistics.

Parameters

Header parameters
Accept string
The content type that the client can understand.
Allowed values: application/json , application/jsonl , application/vnd.apache.parquet , text/csv
Default: application/json
Content-Type string
The format of the data in the request body.
Allowed values: application/json

Request body

Content-Type: application/json
Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/api/v3/query_sql" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"db":"mydb","format":"json","params":{},"q":"SELECT * FROM mytable"}'

Responses

200 Success. The response body contains query results.
results object[]
Example request body
{
  "results": [
    {
      "series": [
        {
          "columns": [
            "time",
            "value"
          ],
          "name": "mytable",
          "values": [
            [
              "2024-02-02T12:00:00Z",
              42
            ]
          ]
        }
      ]
    }
  ]
}
400 Bad request.
401 Unauthorized access.
data object
error string
403 Access denied.
404 Database not found.
405 Method not allowed.
422 Unprocessable entity.
GET /api/v3/query_sql_telemetry

Get query telemetry (beta)

Returns detailed execution statistics for the most recent SQL query, including per-chunk I/O, cache hit rates, and timing breakdowns.

Use this endpoint after executing a query to analyze performance.

Beta: This endpoint requires the performance upgrade preview (--use-pacha-tree flag). The performance upgrade preview is a beta feature and should not be used for production workloads.

For more information, see Query telemetry.

Example request Ask AI about this
curl --request GET \
  "https://localhost:8181/api/v3/query_sql_telemetry" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. Returns query telemetry data.
cache_stats object
Cache hit rates by type.
compacted_hits integer
compacted_misses integer
gen0_hits integer
gen0_misses integer
chunks object[]
Per-chunk statistics.
blocks_processed integer
bytes_read integer
chunk_id string
files_scanned integer
rows_read integer
rows_returned integer
execution_time_us integer
Total execution time in microseconds.
query_id string
Unique identifier for the query.
401 Unauthorized access.
data object
error string
POST /api/v3/query_sql_telemetry

Get query telemetry (beta)

Returns detailed execution statistics for the most recent SQL query, including per-chunk I/O, cache hit rates, and timing breakdowns.

Use this endpoint after executing a query to analyze performance.

Beta: This endpoint requires the performance upgrade preview (--use-pacha-tree flag). The performance upgrade preview is a beta feature and should not be used for production workloads.

For more information, see Query telemetry.

Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/api/v3/query_sql_telemetry" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. Returns query telemetry data.
401 Unauthorized access.
data object
error string
GET /query v1

Execute InfluxQL query (v1-compatible)

Executes an InfluxQL query to retrieve data from the specified database.

This endpoint is compatible with InfluxDB 1.x client libraries and third-party integrations such as Grafana. Use query parameters to specify the database and the InfluxQL query.

Parameters

Query parameters
chunked boolean
If true, the response is divided into chunks of size chunk_size.
chunk_size integer
The number of records that will go into a chunk. This parameter is only used if chunked=true.
Default: 10000
db string <InfluxQL>
The database to query. If not provided, the InfluxQL query string must specify the database.
pretty boolean
If true, the JSON response is formatted in a human-readable format.
q required string
The InfluxQL query string.
epoch string
Formats timestamps as unix (epoch) timestamps with the specified precision instead of RFC3339 timestamps with nanosecond precision.
u string
Username for v1 compatibility authentication. When using Basic authentication or query string authentication, InfluxDB 3 ignores this parameter but allows any arbitrary string for compatibility with InfluxDB 1.x clients.
p string
Password for v1 compatibility authentication. For query string authentication, pass a database token with write permissions as this parameter. InfluxDB 3 checks that the p value is an authorized token.
rp string
Retention policy name. Honored but discouraged. InfluxDB 3 doesn’t use retention policies.
Header parameters
Accept string

The content type that the client can understand.

If text/csv is specified, the Content-type response header is application/csv and the response is formatted as CSV.

Returns an error if the format is invalid or non-UTF8.

Allowed values: application/json , application/csv , text/csv
Default: application/json
Authorization string

Authorization header for token-based authentication. Supported schemes:

  • Bearer AUTH_TOKEN - OAuth bearer token scheme
  • Token AUTH_TOKEN - InfluxDB v2 token scheme
  • Basic <base64-encoded USERNAME:AUTH_TOKEN> - Basic authentication (username is ignored)
Example request Ask AI about this
curl --request GET \
  "https://localhost:8181/query?q=Q" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains query results.
results object[]
Example request body
{
  "results": [
    {
      "series": [
        {
          "columns": [
            "time",
            "value"
          ],
          "name": "mytable",
          "values": [
            [
              "2024-02-02T12:00:00Z",
              42
            ]
          ]
        }
      ]
    }
  ]
}
400 Bad request.
401 Unauthorized access.
data object
error string
403 Access denied.
404 Database not found.
405 Method not allowed.
422 Unprocessable entity.
POST /query v1

Execute InfluxQL query (v1-compatible)

Executes an InfluxQL query to retrieve data from the specified database.

Parameters

Header parameters
Accept string

The content type that the client can understand.

If text/csv is specified, the Content-type response header is application/csv and the response is formatted as CSV.

Returns an error if the format is invalid or non-UTF8.

Allowed values: application/json , application/csv , text/csv
Default: application/json

Request body

Content-Type: application/json
chunk_size integer
The number of records that will go into a chunk. This parameter is only used if chunked=true.
Default: 10000
chunked boolean
If true, the response is divided into chunks of size chunk_size.
db string
The database to query. If not provided, the InfluxQL query string must specify the database.
epoch string

A unix timestamp precision.

  • h for hours
  • m for minutes
  • s for seconds
  • ms for milliseconds
  • u or µ for microseconds
  • ns for nanoseconds

Formats timestamps as unix (epoch) timestamps with the specified precision instead of RFC3339 timestamps with nanosecond precision.

Allowed: ns , u , µ , ms , s , m , h
pretty boolean
If true, the JSON response is formatted in a human-readable format.
q required string
The InfluxQL query string.
Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/query" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "chunk_size": 10000,
  "chunked": false,
  "db": "DB",
  "epoch": "ns",
  "pretty": false,
  "q": "Q"
}'

Responses

200 Success. The response body contains query results.
results object[]
Example request body
{
  "results": [
    {
      "series": [
        {
          "columns": [
            "time",
            "value"
          ],
          "name": "mytable",
          "values": [
            [
              "2024-02-02T12:00:00Z",
              42
            ]
          ]
        }
      ]
    }
  ]
}
400 Bad request.
401 Unauthorized access.
data object
error string
403 Access denied.
404 Database not found.
405 Method not allowed.
422 Unprocessable entity.

Was this page helpful?

Thank you for your feedback!