Query data from TSDB for InfluxDB using the HTTP API - Time Series Database

The HTTP API is the primary way to query data from TSDB for InfluxDB®. For other query methods, see the command-line interface and client documentation.

The examples in this topic use curl.

Send a query

Send a GET request to the /query endpoint. Set db to the target database and q to the InfluxQL statement.

curl -G 'https://<network address>:3242/query?u=<username>&p=<password>&pretty=true' \
  --data-urlencode "db=mydb" \
  --data-urlencode "q=SELECT \"value\" FROM \"cpu_load_short\" WHERE \"region\"='us-west'"

TSDB for InfluxDB® returns results in JSON. Query results appear in the results array. If an error occurs, the error message appears in the error field.

{
    "results": [
        {
            "statement_id": 0,
            "series": [
                {
                    "name": "cpu_load_short",
                    "columns": ["time", "value"],
                    "values": [
                        ["2015-01-29T21:55:43.702900257Z", 2],
                        ["2015-01-29T21:55:43.702900257Z", 0.55],
                        ["2015-06-11T20:46:02Z", 0.64]
                    ]
                }
            ]
        }
    ]
}

You can also send a POST request with the same parameters, either as URL parameters or as an application/x-www-form-urlencoded body.

Query string parameters

Parameter	Required	Description
`db`	Required for database-dependent queries	The target database.
`q`	Required	The InfluxQL query string.
`u`	Required if authentication is enabled	The username.
`p`	Required if authentication is enabled	The password.
`pretty`	Optional	Set to `true` to enable formatted JSON output. Useful for debugging. Do not use in production — it consumes unnecessary network bandwidth.
`epoch`	Optional	Returns timestamps as UNIX timestamps with the specified precision. Valid values: `h` (hours), `m` (minutes), `s` (seconds), `ms` (milliseconds), `u` (microseconds), `ns` (nanoseconds).
`chunked`	Optional	Set to `true` to stream results in batches instead of a single response. Results are chunked by series or by every 10,000 data points, whichever occurs first.
`chunk_size`	Optional	The maximum number of data points per chunk. Requires `chunked=true`.

Multiple queries

Separate multiple InfluxQL statements with a semicolon to send them in a single request:

curl -G 'https://<network address>:3242/query?u=<username>&p=<password>&pretty=true' \
  --data-urlencode "db=mydb" \
  --data-urlencode "q=SELECT \"value\" FROM \"cpu_load_short\" WHERE \"region\"='us-west';SELECT count(\"value\") FROM \"cpu_load_short\" WHERE \"region\"='us-west'"

Each statement maps to a separate entry in the results array, identified by statement_id:

{
    "results": [
        {
            "statement_id": 0,
            "series": [
                {
                    "name": "cpu_load_short",
                    "columns": ["time", "value"],
                    "values": [
                        ["2015-01-29T21:55:43.702900257Z", 2],
                        ["2015-01-29T21:55:43.702900257Z", 0.55],
                        ["2015-06-11T20:46:02Z", 0.64]
                    ]
                }
            ]
        },
        {
            "statement_id": 1,
            "series": [
                {
                    "name": "cpu_load_short",
                    "columns": ["time", "count"],
                    "values": [
                        ["1970-01-01T00:00:00Z", 3]
                    ]
                }
            ]
        }
    ]
}

Timestamp format

All data in TSDB for InfluxDB® is stored and returned in UTC. By default, timestamps use RFC3339 format with nanosecond precision — for example, 2015-08-04T19:05:14.318570484Z.

To get UNIX timestamps instead, set the epoch parameter to the desired precision:

curl -G 'https://<network address>:3242/query?u=<username>&p=<password>' \
  --data-urlencode "db=mydb" \
  --data-urlencode "epoch=s" \
  --data-urlencode "q=SELECT \"value\" FROM \"cpu_load_short\" WHERE \"region\"='us-west'"

Chunked responses

For large result sets, enable chunking to stream results in batches rather than waiting for a single response. Set chunked=true and optionally chunk_size to control the batch size:

curl -G 'https://<network address>:3242/query?u=<username>&p=<password>' \
  --data-urlencode "db=deluge" \
  --data-urlencode "chunked=true" \
  --data-urlencode "chunk_size=20000" \
  --data-urlencode "q=SELECT * FROM liters"

Without chunk_size, results are chunked by series or by every 10,000 data points, whichever occurs first.

Next steps

To learn InfluxQL, see Data exploration.
For the full HTTP API reference, see HTTP API.

InfluxDB® is a trademark registered by InfluxData, which is not affiliated with, and does not endorse, TSDB for InfluxDB®.