Documentation

Use the InfluxDB v3 HTTP query API

Use the InfluxDB 3 HTTP query API to query data in InfluxDB 3 Enterprise. The API provides GET and POST endpoints for querying data and system information using SQL or InfluxQL.

Query using gRPC or HTTP

InfluxDB 3 supports HTTP and Flight (gRPC) query APIs. For more information about using Flight, see the InfluxDB 3 (influxdb3-) client libraries.

The examples below use cURL to send HTTP requests to the InfluxDB 3 HTTP API, but you can use any HTTP client.

Query using SQL and the HTTP API

Use the /api/v3/query_sql endpoint with the GET or POST request methods.

  • GET: Pass parameters in the URL query string (for simple queries)
  • POST: Pass parameters in a JSON object (for complex queries and readability in your code)

Include the following parameters:

  • q: (Required) The SQL query to execute.
  • db: (Required) The database to execute the query against.
  • params: A JSON object containing parameters to be used in a parameterized query.
  • format: The format of the response (json, jsonl, csv, pretty, or parquet). JSONL (jsonl) is preferred because it streams results back to the client. pretty is for human-readable output. Default is json.

Example: Query passing URL-encoded parameters

The following example sends an HTTP GET request with a URL-encoded SQL query:

curl "http://localhost:8181/api/v3/query_sql?db=servers&q=select+*+from+cpu+limit+5" \
  --header "Authorization: Bearer AUTH_TOKEN"
  • Copy
  • Fill window

Example: Query passing JSON parameters

The following example sends an HTTP POST request with parameters in a JSON payload:

curl http://localhost:8181/api/v3/query_sql \
  --header "Authorization: Bearer AUTH_TOKEN" 
  --json '{"db": "server", "q": "select * from cpu limit 5"}'
  • Copy
  • Fill window

Query system information

Use the HTTP API /api/v3/query_sql endpoint to retrieve system information about your database server and table schemas in InfluxDB 3 Enterprise.

Examples

system_ sample data

In examples, tables with "table_name":"system_ are user-created tables for CPU, memory, disk, network, and other resource statistics collected and written by the user–for example, using the psutil Python library or Telegraf to collect and write system metrics to an InfluxDB 3 database.

Show tables

The following example sends a GET request that executes a show tables query to retrieve all user-created tables ("table_schema":"iox"), system tables, and information schema tables for a database:

curl "http://localhost:8181/api/v3/query_sql?db=mydb&format=jsonl&q=show%20tables" \
  --header "Authorization: Bearer AUTH_TOKEN"
  • Copy
  • Fill window

The response body contains the following JSONL:

{"table_catalog":"public","table_schema":"iox","table_name":"system_cpu","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_cpu_cores","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_memory","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_memory_faults","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_disk_usage","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_disk_io","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_disk_performance","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_network","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"system","table_name":"distinct_caches","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"system","table_name":"last_caches","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"system","table_name":"parquet_files","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"system","table_name":"processing_engine_plugins","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"system","table_name":"processing_engine_triggers","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"system","table_name":"queries","table_type":"BASE TABLE"}
{"table_catalog":"public","table_schema":"information_schema","table_name":"tables","table_type":"VIEW"}
{"table_catalog":"public","table_schema":"information_schema","table_name":"views","table_type":"VIEW"}
{"table_catalog":"public","table_schema":"information_schema","table_name":"columns","table_type":"VIEW"}
{"table_catalog":"public","table_schema":"information_schema","table_name":"df_settings","table_type":"VIEW"}
{"table_catalog":"public","table_schema":"information_schema","table_name":"schemata","table_type":"VIEW"}
  • Copy
  • Fill window

A table has one of the following table_schema values:

  • iox: tables created by the user of the database.
  • system: tables used by the system to show information about the running database server. Some of these tables show stored information such as configurations, while others, such as the queries table, hold ephemeral state in memory.
  • information_schema: views that show schema information for tables in the database.

View column information for a table

The following query sends a POST request that executes an SQL query to retrieve information about columns in the sample system_swap table schema:

Note: when you send a query in JSON, you must escape single quotes that surround field names.

curl "http://localhost:8181/api/v3/query_sql" \
  --header "Authorization: Bearer AUTH_TOKEN" \
  --json '{
    "db": "mydb",
    "q": "SELECT * FROM information_schema.columns WHERE table_schema = '"'iox'"' AND table_name = '"'system_swap'"'",
    "format": "jsonl"
  }'
  • Copy
  • Fill window

The output is similar to the following:

{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"free","ordinal_position":0,"is_nullable":"YES","data_type":"UInt64"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"host","ordinal_position":1,"is_nullable":"NO","data_type":"Dictionary(Int32, Utf8)"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"percent","ordinal_position":2,"is_nullable":"YES","data_type":"Float64","numeric_precision":24,"numeric_precision_radix":2}
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"sin","ordinal_position":3,"is_nullable":"YES","data_type":"UInt64"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"sout","ordinal_position":4,"is_nullable":"YES","data_type":"UInt64"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"time","ordinal_position":5,"is_nullable":"NO","data_type":"Timestamp(Nanosecond, None)"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"total","ordinal_position":6,"is_nullable":"YES","data_type":"UInt64"}
{"table_catalog":"public","table_schema":"iox","table_name":"system_swap","column_name":"used","ordinal_position":7,"is_nullable":"YES","data_type":"UInt64"}
  • Copy
  • Fill window

Recently executed queries

To view recently executed queries, query the queries system table:

curl "http://localhost:8181/api/v3/query_sql" \
  --header "Authorization: Bearer AUTH_TOKEN" \
  --json '{
    "db": "mydb",
    "q": "SELECT * FROM system.queries LIMIT 2",
    "format": "jsonl"
  }'
  • Copy
  • Fill window

The output is similar to the following:

{"id":"cdd63409-1822-4e65-8e3a-d274d553dbb3","phase":"success","issue_time":"2025-01-20T17:01:40.690067","query_type":"sql","query_text":"show tables","partitions":0,"parquet_files":0,"plan_duration":"PT0.032689S","permit_duration":"PT0.000202S","execute_duration":"PT0.000223S","end2end_duration":"PT0.033115S","compute_duration":"P0D","max_memory":0,"success":true,"running":false,"cancelled":false}
{"id":"47f8d312-5e75-4db2-837a-6fcf94c09927","phase":"success","issue_time":"2025-01-20T17:02:32.627782","query_type":"sql","query_text":"show tables","partitions":0,"parquet_files":0,"plan_duration":"PT0.000583S","permit_duration":"PT0.000015S","execute_duration":"PT0.000063S","end2end_duration":"PT0.000662S","compute_duration":"P0D","max_memory":0,"success":true,"running":false,"cancelled":false}
  • Copy
  • Fill window

Query using InfluxQL and the HTTP API

Use the /api/v3/query_influxql endpoint with the GET or POST request methods.

  • GET: Pass parameters in the URL query string (for simple queries)
  • POST: Pass parameters in a JSON object (for complex queries and readability in your code)

Include the following parameters:

  • q: (Required) The InfluxQL query to execute.
  • db: (Required) The database to execute the query against.
  • params: A JSON object containing parameters to be used in a parameterized query.
  • format: The format of the response (json, jsonl, csv, pretty, or parquet). JSONL (jsonl) is preferred because it streams results back to the client. pretty is for human-readable output. Default is json.

Example: Query passing URL-encoded parameters

The following example sends an HTTP GET request with a URL-encoded InfluxQL query:

curl "http://localhost:8181/api/v3/query_influxql?db=servers&q=select+*+from+cpu+limit+5" \
  --header "Authorization: Bearer AUTH_TOKEN"
  • Copy
  • Fill window

Example: Query passing JSON parameters

The following example sends an HTTP POST request with parameters in a JSON payload:

curl http://localhost:8181/api/v3/query_influxql \
  --header "Authorization: Bearer AUTH_TOKEN" \ 
  --json '{"db": "server", "q": "select * from cpu limit 5"}'
  • Copy
  • Fill window

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: