Time Series Database:HTTP API

Run a SELECT query

curl -G 'https://<domain-name>:3242/query?db=mydb&u=<username>&p=<password>' \
  --data-urlencode 'q=SELECT * FROM "mymeas"'

Response:

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:16:18Z",33.1,null,null],["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

The same data in the CLI:

name: mymeas
time                  myfield  mytag1  mytag2
----                  -------  ------  ------
2017-03-01T00:16:18Z  33.1
2017-03-01T00:17:18Z  12.4     12      14

Run a SELECT ... INTO query

SELECT ... INTO writes results to a new measurement and requires POST:

curl -XPOST 'https://<domain-name>:3242/query?db=mydb&u=<username>&p=<password>' \
  --data-urlencode 'q=SELECT * INTO "newmeas" FROM "mymeas"'

Response:

{"results":[{"statement_id":0,"series":[{"name":"result","columns":["time","written"],"values":[["1970-01-01T00:00:00Z",2]]}]}]}

Two points were written to newmeas. The timestamp 1970-01-01T00:00:00Z (epoch 0) is used for null timestamps.

Return pretty-printed JSON

curl -G 'https://<domain-name>:3242/query?db=mydb&pretty=true&u=<username>&p=<password>' \
  --data-urlencode 'q=SELECT * FROM "mymeas"'

Response:

{
    "results": [
        {
            "statement_id": 0,
            "series": [
                {
                    "name": "mymeas",
                    "columns": ["time", "myfield", "mytag1", "mytag2"],
                    "values": [
                        ["2017-03-01T00:16:18Z", 33.1, null, null],
                        ["2017-03-01T00:17:18Z", 12.4, "12", "14"]
                    ]
                }
            ]
        }
    ]
}

Return epoch timestamps

curl -G 'https://<domain-name>:3242/query?db=mydb&epoch=s&u=<username>&p=<password>' \
  --data-urlencode 'q=SELECT * FROM "mymeas"'

Response:

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[[1488327378,33.1,null,null],[1488327438,12.4,"12","14"]]}]}]}

Send multiple queries

Separate queries with semicolons. Each result in the response is identified by statement_id, starting at 0.

curl -G 'https://<domain-name>:3242/query?db=mydb&epoch=s&u=<username>&p=<password>' \
  --data-urlencode 'q=SELECT * FROM "mymeas";SELECT mean("myfield") FROM "mymeas"'

Response:

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[[1488327378,33.1,null,null],[1488327438,12.4,"12","14"]]}]},{"statement_id":1,"series":[{"name":"mymeas","columns":["time","mean"],"values":[[0,22.75]]}]}]}

Request CSV output

curl -H "Accept: application/csv" \
  -G 'https://<domain-name>:3242/query?db=mydb&u=<username>&p=<password>' \
  --data-urlencode 'q=SELECT * FROM "mymeas"'

Response:

name,tags,time,myfield,mytag1,mytag2
mymeas,,1488327378000000000,33.1,mytag1,mytag2
mymeas,,1488327438000000000,12.4,12,14

Empty tag columns appear blank. Timestamps are epoch nanoseconds.

Submit queries from a file

curl -F "q=@queries.txt" -F "async=true" \
  'https://<domain-name>:3242/query?u=<username>&p=<password>'

Example queries.txt:

SELECT * FROM "mymeas";
SELECT mean("myfield") FROM "mymeas";

Bind a tag value parameter

curl -G 'https://<domain-name>:3242/query?db=mydb&u=<username>&p=<password>' \
  --data-urlencode 'q=SELECT * FROM "mymeas" WHERE "mytag1" = $tag_value' \
  --data-urlencode 'params={"tag_value":"12"}'

Response:

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

$tag_value is mapped to "12". Tag values are stored as strings and must be double-quoted.

Bind a numeric field value parameter

curl -G 'https://<domain-name>:3242/query?db=mydb&u=<username>&p=<password>' \
  --data-urlencode 'q=SELECT * FROM "mymeas" WHERE "myfield" > $field_value' \
  --data-urlencode 'params={"field_value":30}'

Response:

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:16:18Z",33.1,null,null]]}]}]}

$field_value is mapped to 30. Numeric values do not need quotes.

Bind multiple parameters

curl -G 'https://<domain-name>:3242/query?db=mydb&u=<username>&p=<password>' \
  --data-urlencode 'q=SELECT * FROM "mymeas" WHERE "mytag1" = $tag_value AND "myfield" < $field_value' \
  --data-urlencode 'params={"tag_value":"12","field_value":30}'

Response:

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

Examples

A successful query:

curl -i -G 'https://<domain-name>:3242/query?db=mydb&u=<username>&p=<password>' \
  --data-urlencode 'q=SELECT * FROM "mymeas"'

HTTP/1.1 200 OK
Content-Type: application/json
X-Influxdb-Version: 1.7.x
Transfer-Encoding: chunked

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:16:18Z",33.1,null,null],["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

A query that references a database that does not exist still returns 200, with the error in the JSON body:

curl -i -G 'https://<domain-name>:3242/query?db=mydb1&u=<username>&p=<password>' \
  --data-urlencode 'q=SELECT * FROM "mymeas"'

HTTP/1.1 200 OK
...
{"results":[{"statement_id":0,"error":"database not found: mydb1"}]}

A malformed query:

curl -i -G 'https://<domain-name>:3242/query?db=mydb&u=<username>&p=<password>' \
  --data-urlencode 'q=SELECT *'

HTTP/1.1 400 Bad Request
...
{"error":"error parsing query: found EOF, expected FROM at line 1, char 9"}

A query with invalid credentials:

curl -i -XPOST 'https://<domain-name>:3242/query?u=myusername&p=notmypassword' \
  --data-urlencode 'q=CREATE DATABASE "mydb"'

HTTP/1.1 401 Unauthorized
...
{"error":"authorization failed"}

Write a point with a second-precision timestamp

curl -i -XPOST "https://<domain-name>:3242/write?db=mydb&precision=s&u=<username>&p=<password>" \
  --data-binary 'mymeas,mytag=1 myfield=90 1463683075'

HTTP/1.1 204 No Content

Write a point to a specific retention policy

curl -i -XPOST "https://<domain-name>:3242/write?db=mydb&rp=myrp&u=<username>&p=<password>" \
  --data-binary 'mymeas,mytag=1 myfield=90'

HTTP/1.1 204 No Content

Write using HTTP authentication (query string)

Valid credentials:

curl -i -XPOST "https://<domain-name>:3242/write?db=mydb&u=myusername&p=mypassword" \
  --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 204 No Content

Invalid credentials:

curl -i -XPOST "https://<domain-name>:3242/write?db=mydb&u=myusername&p=notmypassword" \
  --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 401 Unauthorized
...
{"error":"authorization failed"}

Write using basic authentication

Valid credentials:

curl -i -XPOST -u myusername:mypassword "https://<domain-name>:3242/write?db=mydb" \
  --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 204 No Content

Invalid credentials:

curl -i -XPOST -u myusername:notmypassword "https://<domain-name>:3242/write?db=mydb" \
  --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 401 Unauthorized
...
{"error":"authorization failed"}

Write a point with a nanosecond timestamp

curl -i -XPOST "https://<domain-name>:3242/write?db=mydb&u=<username>&p=<password>" \
  --data-binary 'mymeas,mytag=1 myfield=90 1463683075000000000'

HTTP/1.1 204 No Content

Write a point using the server timestamp

Omit the timestamp to use the server's current nanosecond time:

curl -i -XPOST "https://<domain-name>:3242/write?db=mydb&u=<username>&p=<password>" \
  --data-binary 'mymeas,mytag=1 myfield=90'

HTTP/1.1 204 No Content

Write multiple points in one request

curl -i -XPOST "https://<domain-name>:3242/write?db=mydb&u=<username>&p=<password>" \
  --data-binary 'mymeas,mytag=3 myfield=89 1463689152000000000
mymeas,mytag=2 myfield=34 1463689152000000000'

HTTP/1.1 204 No Content

Write points from a file

curl -i -XPOST "https://<domain-name>:3242/write?db=mydb&u=<username>&p=<password>" \
  --data-binary @data.txt

Example data.txt:

mymeas,mytag1=1 value=21 1463689680000000000
mymeas,mytag1=1 value=34 1463689690000000000
mymeas,mytag2=8 value=78 1463689700000000000
mymeas,mytag3=9 value=89 1463689710000000000

Examples

Successful write:

HTTP/1.1 204 No Content

Invalid timestamp:

HTTP/1.1 400 Bad Request
{"error":"unable to parse 'mymeas,mytag=1 myfield=91 abc123': bad timestamp"}

Field type conflict (writing an integer to a field previously stored as float):

HTTP/1.1 400 Bad Request
{"error":"field type conflict: input field \"myfield\" on measurement \"mymeas\" is type int64, already exists as type float"}

Invalid credentials:

HTTP/1.1 401 Unauthorized
{"error":"authorization failed"}

Target database does not exist:

HTTP/1.1 404 Not Found
{"error":"database not found: \"mydb1\""}

Target retention policy does not exist:

HTTP/1.1 500 Internal Server Error
{"error":"retention policy not found: myrp"}

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