All Products
Search
Document Center

HTTP API

Last Updated: Sep 07, 2020

The HTTP API of Time Series Database (TSDB) for InfluxDB® provides a simple way to interact with databases. This API authenticates requests by using HTTP authentication, JSON Web Tokens (JWT), and basic authentication, and returns HTTP status codes and responses in JSON format.

This topic describes the HTTP API endpoints provided by a TSDB for InfluxDB® instance. The examples assume that the instance runs on and the 3242 port, and HTTPS is enabled.

TSDB for InfluxDB® HTTP API endpoints

Endpoint Description
/debug/pprof Generates profiles for troubleshooting.``
/debug/requests `Tracks requests sent by HTTP clients to the/write or/query` endpoints.
/debug/vars Collects statistics.``
/ping Queries the status and version of the TSDB for InfluxDB® instance.``
/query Queries data and manages databases, retention policies (RPs), and users.``
/write Writes data to an existing database.``

/debug/pprof HTTP endpoint

TSDB for InfluxDB® supports the Go net/http/pprof HTTP endpoints, which are useful for troubleshooting. The pprof package provides real-time data analysis and provides output in the format accepted by the pprof visualization tool.

Definition

  1. curl https://<Domain name>:3242/debug/pprof?u=<Username>&p=<Password>

The /debug/pprof/ endpoint generates an HTML page that contains the built-in Go profiles and corresponding hyperlinks.

Profile Description
block Stack traces that led to blocking on synchronization primitives.
goroutine Stack traces of all current goroutines.
heap A sample of stack traces for heap allocations.
mutex Stack traces of holders of contended mutexes.
threadcreate Stack traces that led to the creation of new OS threads.

To access one of preceding /debug/pprof/ profiles, run the following curl command. Replace <profile> with the target profile name. The final profile is output to the file specified in .

  1. curl -o <path/to/output-file> https://<Domain name>:3242/debug/pprof/<profile>?u=<Username>&p=<Password>

Run the following curl command to output the resulting heap profile to a file:

  1. curl -o <path/to/output-file> https://<Domain name>:3242/debug/pprof/heap?u=<Username>&p=<Password>

You can also use the Go pprof interactive tool to access the /debug/pprof/ profiles of TSDB for InfluxDB®. For example, to use this tool to view heap profiles of a TSDB for InfluxDB® instance, you can run the following command:

  1. go tool pprof https://<Domain name>:3242/debug/pprof/heap?u=<Username>&p=<Password>

For more information about the Go /net/http/pprof package and the interactive pprof analysis and visualization tool, see:

/debug/pprof/all HTTP endpoint

The /debug/pprof/all endpoint is a custom /debug/pprof profile. It generates the profile.tar.gz package that contains standard Go profiling information and other debugging data. If you use the cpu=true setting (by default, cpu=false), an optional CPU profile is generated.

To create profile.tar.gz, run the following curl command:

  1. curl -o profiles.tar.gz "https://<Domain name>:3242/debug/pprof/all?cpu=true&u=<Username>&p=<Password>"

Note: If you use the cpu=true setting, it takes more than 30 seconds to generate a CPU profile. If you worry about running the CPU profile (which only has small and temporary impact on performance), you can set ? cpu=false or omit ? cpu=true.

In the following example, the curl command output includes Time Spent (in seconds). After the data of 30 seconds is collected, the results are output to a file.

  1. ~ curl -o profiles.tar.gz "https://<Domain name>:3242/debug/pprof/all?cpu=true&u=<Username>&p=<Password>"
  2. % Total % Received % Xferd Average Speed Time Time Time Current
  3. Dload Upload Total Spent Left Speed
  4. 100 237k 0 237k 0 0 8025 0 --:--:-- 0:00:30 --:--:-- 79588

/debug/requests HTTP endpoint

Use /debug/requests to trace requests sent by HTTP clients to the /write and /query endpoints. This endpoint returns the numbers of write requests and query requests sent by each user and IP address to TSDB for InfluxDB®.

Definition

  1. curl https://<Domain name>:3242/debug/requests?u=<Username>&p=<Password>

String query parameters

String query parameters Optional/Required Definition
seconds=\ Optional The duration (in seconds) in which the client collects information. The default duration is 10 seconds.

Examples

Track requests in the last 10 seconds

  1. $ curl https://<Domain name>:3242/debug/requests?u=<Username>&p=<Password>
  2. {
  3. "user1:123.45.678.91": {"writes":1,"queries":0},
  4. }

The response shows that, over the last 10 seconds, user1 sent one request from 123.45.678.91 to the /write endpoint, but did not send requests to the /query endpoint.

Track requests in the last one minute

  1. $ curl https://<Domain name>:3242/debug/requests?seconds=60&u=<Username>&p=<Password>
  2. {
  3. "user1:123.45.678.91": {"writes":3,"queries":0},
  4. "user1:000.0.0.0": {"writes":0,"queries":16},
  5. "user2:xx.xx.xxx.xxx": {"writes":4,"queries":0}
  6. }

The output shows that, in the last one minute, user1 sent three requests from 123.45.678.91 to the /write endpoint and 16 requests from 000.0.0.0 to the /query endpoint, and user2 sent four requests from xx.xx.xxx.xxx to the /write endpoint.``

/debug/vars HTTP endpoint

TSDB for InfluxDB® uses /debug/vars to expose its statistics about its runtime. You can run the following curl command to query the statistics:

  1. curl https://<Domain name>:3242/debug/vars?u=<Username>&p=<Password>

Statistics of the server are displayed in JSON format.

/ping HTTP endpoint

The /ping endpoint accepts both GET and HEAD HTTP requests. Use /ping to check the TSDB for InfluxDB® version and instance status.

Definition

  1. GET https://<Domain name>:3242/ping?u=<Username>&p=<Password>
  1. HEAD https://<Domain name>:3242/ping?u=<Username>&p=<Password>

verbose option

By default, the /ping endpoint returns the HTTP 204 status code to notify the client that the server is running. The default value of verbose is false. If verbose is set to true (/ping?verbose=true), the HTTP 200 status code is returned.

Examples

You can use the /ping endpoint to view the version of the TSDB for InfluxDB® instance. The x-Influxdb-Version header field shows the version.

  1. ~ curl -sl -I https://<Domain name>:3242/ping?u=<Username>&p=<Password>
  2. HTTP/1.1 204 No Content
  3. Content-Type: application/json
  4. Request-Id: 9c353b0e-aadc-11e8-8023-000000000000
  5. X-Influxdb-Build: OSS
  6. X-Influxdb-Version: v1.7.x
  7. X-Request-Id: 9c353b0e-aadc-11e8-8023-000000000000
  8. Date: Tue, 05 Nov 2018 16:08:32 GMT

Status codes and responses

The body of the response is empty.

HTTP status code Description
204 The request is successful. The TSDB for InfluxDB® instance is running.

/query HTTP endpoint

The /query endpoint accepts GET and POST HTTP requests. Use this endpoint to query data and manage databases, RPs, and users.

Definition

  1. GET https://<Domain name>:3242/query?u=<Username>&p=<Password>
  1. POST https://<Domain name>:3242/query?u=<Username>&p=<Password>

Verb usage

Verb Query type
GET This verb is used for all queries that start with the following keywords:
SELECT
SHOW
POST This verb is used for all queries that start with the following keywords:
ALTER
CREATE
DELETE
DROP
GRANT
KILL
REVOKE

* The only exceptions are SELECT query statements that include the INTO clause, which require POST requests.

Examples

Run SELECT statements to query data

  1. $ curl -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas"'
  2. {"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 mymeas measurement has two points. In the first point, the timestamp is 2017-03-01T00:16:18Z, the value of the myfield field key is 33.1, and the mytag1 and mytag2 tag keys have no values. In the second point, the timestamp is 2017-03-01T00:17:18Z, the value of the myfield field key is 12.4, the value of the mytag1 tag key is 12, and the value of the mytag2 tag key is 14.

The same query in the TSDB for InfluxDB® command-line interface (CLI) returns the following table.

  1. name: mymeas
  2. time myfield mytag1 mytag2
  3. ---- ------- ------ ------
  4. 2017-03-01T00:16:18Z 33.1
  5. 2017-03-01T00:17:18Z 12.4 12 14

Run SELECT statements that include the INTO clause to query data

  1. $ curl -XPOST 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * INTO "newmeas" FROM "mymeas"'
  2. {"results":[{"statement_id":0,"series":[{"name":"result","columns":["time","written"],"values":[["1970-01-01T00:00:00Z",2]]}]}]}

If you want to run a SELECT statement that includes the INTO clause to query data, POST requests are required.

The response shows that TSDB for InfluxDB® writes two points to the newmeas measurement. The system uses epoch 0 (1970-01-01T00:00:00Z) as an null timestamp.

String query parameters

String query parameters Optional/Required Description
chunked=[true, number_of_points] Optional Returns points in streamed batches instead of in a single response. If this parameter is set to true, TSDB for InfluxDB® chunks responses by series or by every 10,000 points, whichever occurs first. If you specify a number, TSDB for InfluxDB® chunks responses by series or by the specified number of points.
db=database_name Required for database-dependent queries (most SELECT and SHOW queries) Specifies the target database for the query.
epoch=[ns,u,µ,ms,s,m,h] Optional Returns the epoch timestamp of the specified accuracy. By default, TSDB for InfluxDB® returns the nanosecond timestamp that follows the RFC 3339 format. Both u and µ indicate microseconds.
p=password Optional if authentication is not enabled. Required if authentication is enabled. Specifies the password for authentication if authentication is enabled. This parameter must be used with u.
pretty=true Optional Enables pretty-printed JSON output. This is useful for debugging. However, this setting consumes extra network bandwidth. We recommend that you do not enable this option for production.
q=query Required The Influx Query Language (InfluxQL) command to run. For more information, see Request body.
u=username Optional if authentication is not enabled. Required if authentication is enabled. Specifies the username for authentication if authentication is enabled. The user must have the read permission on databases. This parameter must be used with p.

* If the chunked parameter is not used, TSDB for InfluxDB® does not truncate the rows returned for requests.

Examples

Use SELECT statements to query data and return pretty-printed JSON data

  1. $ curl -G 'https://<Domain name>:3242/query?db=mydb&pretty=true&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas"'
  2. {
  3. "results": [
  4. {
  5. "statement_id": 0,
  6. "series": [
  7. {
  8. "name": "mymeas",
  9. "columns": [
  10. "time",
  11. "myfield",
  12. "mytag1",
  13. "mytag2"
  14. ],
  15. "values": [
  16. [
  17. "2017-03-01T00:16:18Z",
  18. 33.1,
  19. null,
  20. null
  21. ],
  22. [
  23. "2017-03-01T00:17:18Z",
  24. 12.4,
  25. "12",
  26. "14"
  27. ]
  28. ]
  29. }
  30. ]
  31. }
  32. ]
  33. }

Use a SELECT statement to query data and return epoch timestamps of accuracies other than nanoseconds.

  1. $ curl -G 'https://<Domain name>:3242/query?db=mydb&epoch=s&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas"'
  2. {"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[[1488327378,33.1,null,null],[1488327438,12.4,"12","14"]]}]}]}

Request body

  1. --data-urlencode "q=<InfluxQL query>"

All queries must be URL encoded and follow InfluxQL syntax. All examples on this page include the --data-urlencode parameter in the curl commands.``

Options

Send multiple queries

Use semicolons (;) to separate multiple queries.

Submit queries in a file

You can use a multipart POST request to submit queries in a file. The queries in the file must be separated with semicolons (;).

Syntax:

  1. curl -F "q=@<path_to_file>" -F "async=true" https://<Domain name>:3242/query?u=<Username>&p=<Password>

Request query results in CSV format

Syntax:

  1. curl -H "Accept: application/csv" -G 'https://<Domain name>:3242/query?u=<Username>&p=<Password>' [...]

If a request includes -H Accept: application/csv, the system returns epoch timestamps rather than RFC 3339 timestamps.

Bind parameters

The HTTP API allows you to bind parameters to specified field values or tag values in WHERE clauses. Use the $<placeholder_key> syntax as a placeholder in the query, and URL encode the map of placeholder keys to placeholder values in the request body.

Query syntax:

  1. --data-urlencode 'q= SELECT [...] WHERE [ <field_key> | <tag_key> ] = $<placeholder_key>'

Map syntax:

  1. --data-urlencode 'params={"<placeholder_key>":[ <placeholder_float_field_value> | <placeholder_integer_field_value> | "<placeholder_string_field_value>" | <placeholder_boolean_field_value> | "<placeholder_tag_value>" ]}'

Use commas (,) to separate multiple placeholder key-value pairs.

Examples

Send multiple queries

  1. $ 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"'
  2. {"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]]}]}]}

The request contains two queries: SELECT * FROM "mymeas" and SELECT mean("myfield") FROM "mymeas". The output shows that the system allocates the statement_id statement identifier to each query returned. The value of statement_id is 0 in the result of the first query. The value of statement_id is 1 in the result of the second query.

Request query results in CSV format

  1. $ curl -H "Accept: application/csv" -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas"'
  2. name,tags,time,myfield,mytag1,mytag2
  3. mymeas,,1488327378000000000,33.1,mytag1,mytag2
  4. mymeas,,1488327438000000000,12.4,12,14

The first point has no tag values for the mytag1 and mytag2 tag keys.

Submit queries in a file

  1. $ curl -F "q=@queries.txt" -F "async=true" 'https://<Domain name>:3242/query?u=<Username>&p=<Password>'

The following is an example of queries in the queries.txt file:

  1. SELECT * FROM "mymeas";
  2. SELECT mean("myfield") FROM "mymeas";

Bind parameters in the WHERE clause to specified tag values

  1. $ 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"}'
  2. {"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

The request maps $tag_value to 12. TSDB for InfluxDB® stores tag values as strings. Therefore, the tag values in the request must be enclosed in double quotation marks (“).

Bind parameters in the WHERE clause to numeric field values

  1. $ 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}'
  2. {"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:16:18Z",33.1,null,null]]}]}]}

The request maps $field_value to 30. The value 30 does not need to be enclosed in double quotation marks (“) because myfield stores numeric field values.

Bind the two parameters in the WHERE clause to a specified tag value and a numeric field value respectively

  1. $ 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}'
  2. {"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

The request maps $tag_value to 12 and $field_value to 30.

Status codes and responses

Responses are returned in JSON format. You can include pretty=true to enable pretty-printed JSON output.

Summary

HTTP status code Description
200 OK The request is successful. For more information, see the JSON output.
400 Bad Request The request cannot be processed. This may be caused by incorrect query syntax. For more information, see the JSON output.
401 Unauthorized The request cannot be processed. This may be caused by invalid credentials for authentication.

Examples

A request that returns data

  1. $ curl -i -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas"'
  2. HTTP/1.1 200 OK
  3. Connection: close
  4. Content-Type: application/json
  5. Request-Id: [...]
  6. X-Influxdb-Version: 1.7.x
  7. Date: Wed, 08 Nov 2017 19:22:54 GMT
  8. Transfer-Encoding: chunked
  9. {"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 request that returns an error

  1. $ curl -i -G 'https://<Domain name>:3242/query?db=mydb1&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT * FROM "mymeas"'
  2. HTTP/1.1 200 OK
  3. Connection: close
  4. Content-Type: application/json
  5. Request-Id: [...]
  6. X-Influxdb-Version: 1.7.x
  7. Date: Wed, 08 Nov 2017 19:23:48 GMT
  8. Transfer-Encoding: chunked
  9. {"results":[{"statement_id":0,"error":"database not found: mydb1"}]}

A query of an incorrect format

  1. $ curl -i -G 'https://<Domain name>:3242/query?db=mydb&u=<Username>&p=<Password>' --data-urlencode 'q=SELECT *'
  2. HTTP/1.1 400 Bad Request
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. X-Influxdb-Version: 1.7.x
  6. Date: Wed, 08 Nov 2017 19:24:25 GMT
  7. Content-Length: 76
  8. {"error":"error parsing query: found EOF, expected FROM at line 1, char 9"}

A query that uses invalid authentication credentials

  1. $ curl -i -XPOST 'https://<Domain name>:3242/query?u=myusername&p=notmypassword' --data-urlencode 'q=CREATE DATABASE "mydb"'
  2. HTTP/1.1 401 Unauthorized
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. Www-Authenticate: Basic realm="InfluxDB"
  6. X-Influxdb-Version: 1.7.x
  7. Date: Wed, 08 Nov 2017 19:11:26 GMT
  8. Content-Length: 33
  9. {"error":"authorization failed"}

/write HTTP endpoint

The /write endpoint accepts POST HTTP requests. Use /write to write data to a created database.

Definition

  1. POST https://<Domain name>:3242/write?u=<Username>&p=<Password>

String query parameters

String query parameters Optional/Required Description
db=\ Required Specifies the target database to which data is written.
p=\ Optional if authentication is not enabled. Required if authentication is enabled. Specifies the password for authentication if authentication is enabled. This parameter must be used with u.
precision=[ns,u,ms,s,m,h] Optional Specifies the accuracy of the provided UNIX timestamp. If you do not set this parameter, TSDB for InfluxDB® assumes that the timestamp is accurate to nanoseconds.
rp=\ Optional Specifies the target RP for the write. If you do not set this parameter, TSDB for InfluxDB® writes data to the default (DEFAULT) RP.
u=\ Optional if authentication is not enabled. Required if authentication is enabled. Specifies the username for authentication if authentication is enabled. The user must have the write permission on databases. This parameter must be used with p.

** We recommend that the time be accurate to the smallest granularity to significantly improve the compression performance.

Examples

Write a point whose timestamp is accurate to seconds to the mydb database

  1. $ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&precision=s&u=<Username>&p=<Password>" --data-binary 'mymeas,mytag=1 myfield=90 1463683075'
  2. HTTP/1.1 204 No Content
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. X-Influxdb-Version: 1.7.x
  6. Date: Wed, 08 Nov 2017 17:33:23 GMT

Write a point to the mydb database and the myrp RP

  1. $ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&rp=myrp&u=<Username>&p=<Password>" --data-binary 'mymeas,mytag=1 myfield=90'
  2. HTTP/1.1 204 No Content
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. X-Influxdb-Version: 1.7.x
  6. Date: Wed, 08 Nov 2017 17:34:31 GMT

Write a point to the mydb database by using HTTP authentication

Valid credentials:

  1. $ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&u=myusername&p=mypassword" --data-binary 'mymeas,mytag=1 myfield=91'
  2. HTTP/1.1 204 No Content
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. X-Influxdb-Version: 1.7.x
  6. Date: Wed, 08 Nov 2017 17:34:56 GMT

Invalid credentials:

  1. $ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&u=myusername&p=notmypassword" --data-binary 'mymeas,mytag=1 myfield=91'
  2. HTTP/1.1 401 Unauthorized
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. Www-Authenticate: Basic realm="InfluxDB"
  6. X-Influxdb-Version: 1.7.x
  7. Date: Wed, 08 Nov 2017 17:40:30 GMT
  8. Content-Length: 33
  9. {"error":"authorization failed"}

Write a point to the mydb database by using basic authentication

Valid credentials:

  1. $ curl -i -XPOST -u myusername:mypassword "https://<Domain name>:3242/write?db=mydb" --data-binary 'mymeas,mytag=1 myfield=91'
  2. HTTP/1.1 204 No Content
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. X-Influxdb-Version: 1.7.x
  6. Date: Wed, 08 Nov 2017 17:36:40 GMT

Invalid credentials:

  1. $ curl -i -XPOST -u myusername:notmypassword "https://<Domain name>:3242/write?db=mydb" --data-binary 'mymeas,mytag=1 myfield=91'
  2. HTTP/1.1 401 Unauthorized
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. Www-Authenticate: Basic realm="InfluxDB"
  6. X-Influxdb-Version: 1.7.x
  7. Date: Wed, 08 Nov 2017 17:46:40 GMT
  8. Content-Length: 33
  9. {"error":"authorization failed"}

Request body

  1. --data-binary '<Data in Line Protocol format>'

All data must be binary encoded and follow the line protocol format. All examples on this page include the --data-binary parameter in the curl commands. If an encoding mode other than --data-binary is used, an error may occur. The -d, --data-urlencode, and --data-ascii modes may remove the line feeds or introduce unexpected formats.

Options:

  • You can write points separated by line feeds to a database in one request.
  • Write points from a file. Use the at sign (@) to reference the file. Points in the file must be organized in line protocol format. Separate all the points with line feeds (\n). If the file contains carriage returns, the request will fail to be parsed.

We recommend that you write data in batches of 5,000 or 10,000 points. If you include a smaller number of points in each batch, a larger number of HTTP requests must be sent. This compromises the performance.

Examples

Write a point that uses a nanosecond timestamp to the mydb database

  1. $ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&u=<Username>&p=<Password>" --data-binary 'mymeas,mytag=1 myfield=90 1463683075000000000'
  2. HTTP/1.1 204 No Content
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. X-Influxdb-Version: 1.7.x
  6. Date: Wed, 08 Nov 2017 18:02:57 GMT

Write a point that uses the nanosecond timestamp of the local server to the mydb database

  1. $ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&u=<Username>&p=<Password>" --data-binary 'mymeas,mytag=1 myfield=90'
  2. HTTP/1.1 204 No Content
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. X-Influxdb-Version: 1.7.x
  6. Date: Wed, 08 Nov 2017 18:03:44 GMT

Write multiple points separated with line feeds to the mydb database

  1. $ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&u=<Username>&p=<Password>" --data-binary 'mymeas,mytag=3 myfield=89 1463689152000000000
  2. mymeas,mytag=2 myfield=34 1463689152000000000'
  3. HTTP/1.1 204 No Content
  4. Content-Type: application/json
  5. Request-Id: [...]
  6. X-Influxdb-Version: 1.7.x
  7. Date: Wed, 08 Nov 2017 18:04:02 GMT

Write multiple points from the data.txt file to the mydb database

  1. $ curl -i -XPOST "https://<Domain name>:3242/write?db=mydb&u=<Username>&p=<Password>" --data-binary @data.txt
  2. HTTP/1.1 204 No Content
  3. Content-Type: application/json
  4. Request-Id: [...]
  5. X-Influxdb-Version: 1.7.x
  6. Date: Wed, 08 Nov 2017 18:08:11 GMT

The following is a sample of the data in the data.txt file:

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

Status codes and responses

In general, 2xx status codes indicate success, 4xx status codes indicate that TSDB for InfluxDB® fails to parse the requests, and 5xx status codes indicate that the system is overloaded or significantly impaired. Errors are returned in JSON format.

Summary

HTTP status code Description
204 No Content The request is successful.
400 Bad Request The request cannot be processed. This may be caused by invalid write protocol syntax or data writes to a field that previously accepted a different value type. For more information, see the JSON output.
401 Unauthorized The request cannot be processed. This may be caused by invalid credentials for authentication.
404 Not Found The request cannot be processed. This may be caused by an attempt to write data to a database that does not exist. For more information, see the JSON output.
500 Internal Server Error The system is overloaded or significantly impaired. This may be caused by an attempt to write data to an RP that does not exist. For more information, see the JSON output.

Examples

Write data successfully

  1. HTTP/1.1 204 No Content

Write a point that uses an incorrect timestamp

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

Write an integer to a field that previously accepted floats

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

Write data by using invalid credentials for authentication

  1. HTTP/1.1 401 Unauthorized
  2. [...]
  3. {"error":"authorization failed"}

Write a point to a database that does not exist

  1. HTTP/1.1 404 Not Found
  2. [...]
  3. {"error":"database not found: \"mydb1\""}

Write a point to an RP that does not exist

  1. HTTP/1.1 500 Internal Server Error
  2. [...]
  3. {"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®.