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

Request body required

Content-Type: 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" \
  --header "Content-Type: application/json"

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

Request body required

Content-Type: 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" \
  --header "Content-Type: application/json"

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 /query

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

Execute InfluxQL query (v1-compatible)

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