The InfluxDB v2 HTTP API for InfluxDB Clustered provides a v2-compatible programmatic interface for writing data stored in an InfluxDB Clustered database.
The InfluxDB v2 HTTP API lets you use /api/v2 endpoints for managing retention policy mappings and writing data stored in an InfluxDB v3 instance.
This documentation is generated from the InfluxDB OpenAPI specification.
See the Get Started tutorial to get up and running authenticating with tokens, writing to databases, and querying data.
InfluxDB API client libraries and Flight clients are available to integrate InfluxDB APIs with your application.
Use one of the following schemes to authenticate to the InfluxDB API:
Use the Authorization header with the Basic scheme to authenticate v1 API /write and /query requests.
When authenticating requests, InfluxDB Clustered checks that the password part of the decoded credential is an authorized database token.
InfluxDB Clustered ignores the username part of the decoded credential.
Authorization: Basic <base64-encoded [USERNAME]:DATABASE_TOKEN>Replace the following:
[USERNAME]: an optional string value (ignored by InfluxDB Clustered).DATABASE_TOKEN: a database token.[USERNAME]:DATABASE_TOKEN credential using base64 encoding, and then append the encoded string to the Authorization: Basic header.The following example shows how to use cURL with the Basic authentication scheme and a database token:
#######################################
# Use Basic authentication with a database token
# to query the InfluxDB v1 HTTP API
#######################################
# Use the --user option with `--user username:DATABASE_TOKEN` syntax
#######################################
curl --get "http://cluster-id.a.influxdb.io/query" \
--user "":"DATABASE_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM MEASUREMENT"Replace the following:
DATABASE_NAME: your InfluxDB Clustered databaseDATABASE_TOKEN: a database token with sufficient permissions to the database| Security Scheme Type | HTTP |
|---|---|
| HTTP Authorization Scheme | basic |
Use the Querystring authentication scheme with InfluxDB 1.x API parameters to provide credentials through the query string.
In the URL, pass the p query parameter to authenticate /write and /query requests.
When authenticating requests, InfluxDB Clustered checks that p (password) is an authorized database token and ignores the u (username) parameter.
https://cluster-id.a.influxdb.io/query/?[u=any]&p=DATABASE_TOKEN
https://cluster-id.a.influxdb.io/write/?[u=any]&p=DATABASE_TOKENThe following example shows how to use cURL with query string authentication and a database token.
#######################################
# Use an InfluxDB 1.x compatible username and password
# to query the InfluxDB v1 HTTP API
#######################################
# Use authentication query parameters:
# ?p=DATABASE_TOKEN
#######################################
curl --get "https://cluster-id.a.influxdb.io/query" \
--data-urlencode "p=DATABASE_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SELECT * FROM MEASUREMENT"Replace the following:
DATABASE_NAME: your InfluxDB Clustered databaseDATABASE_TOKEN: a database token with sufficient permissions to the database| Security Scheme Type | API Key |
|---|---|
| Query parameter name: | u=&p= |
Use the OAuth Bearer authentication scheme to authenticate to the InfluxDB API.
In your API requests, send an Authorization header.
For the header value, provide the word Bearer followed by a space and a database token.
Authorization: Bearer INFLUX_TOKEN########################################################
# Use the Bearer token authentication scheme with /api/v2/write
# to write data.
########################################################
curl --request post "https://cluster-id.a.influxdb.io/api/v2/write?bucket=DATABASE_NAME&precision=s" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--data-binary 'home,room=kitchen temp=72 1463683075'For examples and more information, see the following:
| Security Scheme Type | HTTP |
|---|---|
| HTTP Authorization Scheme | bearer |
| Bearer format | "JWT" |
Use the Token authentication scheme to authenticate to the InfluxDB API.
In your API requests, send an Authorization header.
For the header value, provide the word Token followed by a space and a database token.
The word Token is case-sensitive.
Authorization: Token INFLUX_API_TOKEN########################################################
# Use the Token authentication scheme with /api/v2/write
# to write data.
########################################################
curl --request post "https://cluster-id.a.influxdb.io/api/v2/write?bucket=DATABASE_NAME&precision=s" \
--header "Authorization: Token DATABASE_TOKEN" \
--data-binary 'home,room=kitchen temp=72 1463683075'| Security Scheme Type | API Key |
|---|---|
| Header parameter name: | Authorization |
InfluxDB HTTP API endpoints use standard HTTP request and response headers.
The following table shows common headers used by many InfluxDB API endpoints.
Some endpoints may use other headers that perform functions more specific to those endpoints--for example,
the POST /api/v2/write endpoint accepts the Content-Encoding header to indicate the compression applied to line protocol in the request body.
| Header | Value type | Description |
|---|---|---|
Accept | string | The content type that the client can understand. |
Authorization | string | The authorization scheme and credential. |
Content-Length | integer | The size of the entity-body, in bytes, sent to the database. |
Content-Type | string | The format of the data in the request body. |
InfluxDB HTTP API endpoints use standard HTTP status codes for success and failure responses. The response body may include additional details. For details about a specific operation's response, see Responses and Response Samples for that operation.
API operations may return the following HTTP status codes:
| Code | Status | Description |
|---|---|---|
200 | Success | |
204 | Success. No content | InfluxDB doesn't return data for the request. For example, a successful write request returns 204 status code, acknowledging that data is written and queryable. |
400 | Bad request | InfluxDB can't parse the request due to an incorrect parameter or bad syntax. If line protocol in the request body is malformed. The response body contains the first malformed line and indicates what was expected. For partial writes, the number of points written and the number of points rejected are also included. |
401 | Unauthorized | May indicate one of the following:
|
404 | Not found | Requested resource was not found. message in the response body provides details about the requested resource. |
405 | Method not allowed | The API path doesn't support the HTTP method used in the request--for example, you send a POST request to an endpoint that only allows GET. |
413 | Request entity too large | Request payload exceeds the size limit. |
422 | Unprocessable entity | Request data is invalid. code and message in the response body provide details about the problem. |
429 | Too many requests | API token is temporarily over the request quota. The Retry-After header describes when to try the request again. |
500 | Internal server error | |
503 | Service unavailable | Server is temporarily unavailable to process the request. The Retry-After header describes when to try the request again. |
Retrieves the status and InfluxDB version of the instance.
Use this endpoint to monitor uptime for the InfluxDB instance. The response
returns a HTTP 204 status code to inform you the instance is available.
This endpoint doesn't require authentication.
Returns the status and InfluxDB version of the instance.
Use this endpoint to monitor uptime for the InfluxDB instance. The response
returns a HTTP 204 status code to inform you the instance is available.
This endpoint doesn't require authentication.
Query data stored in a database.
/query endpoint
using InfluxQL and retrieve data in CSV or JSON format./api/v2/query endpoint can't query InfluxDB Clustered.Queries InfluxDB using InfluxQL with InfluxDB v1 request and response formats.
| db required | string The database to query data from. |
| epoch | string Enum: "ns" "u" "µ" "ms" "s" "m" "h" A unix timestamp precision. Formats timestamps as unix (epoch) timestamps the specified precision instead of RFC3339 timestamps with nanosecond precision. |
| p | string The InfluxDB 1.x password to authenticate the request. |
| q required | string The InfluxQL query to execute. To execute multiple queries, delimit queries with a semicolon ( |
| rp | string The retention policy to query data from. For more information, see InfluxQL DBRP naming convention. |
| u | string The InfluxDB 1.x username to authenticate the request. |
| Accept | string Default: application/json Enum: "application/json" "application/csv" "text/csv" "application/x-msgpack" Media type that the client can understand. Note: With |
| Accept-Encoding | string Default: identity Enum: "gzip" "identity" The content encoding (usually a compression algorithm) that the client can understand. |
| Content-Type | string Value: "application/json" |
| Zap-Trace-Span | string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context |
Write time series data to databases using InfluxDB v1 or v2 endpoints.
Writes data to a database.
Use this endpoint to send data in line protocol format to InfluxDB.
InfluxDB does the following when you send a write request:
204 status code), acknowledging that the data is written and queryable; error otherwise.To ensure that InfluxDB Cloud handles writes in the order you request them,
wait for a success response (HTTP 2xx status code) before you send the next request.
| bucket required | string A database name or ID. InfluxDB writes all points in the batch to the specified database. |
| org required | string Ignored. An organization name or ID. InfluxDB ignores this parameter; authorizes the request using the specified database token and writes data to the specified cluster database. |
| orgID | string Ignored. An organization ID. InfluxDB ignores this parameter; authorizes the request using the specified database token and writes data to the specified cluster database. |
| precision | string (WritePrecision) Enum: "ms" "s" "us" "ns" The precision for unix timestamps in the line protocol batch. |
| Accept | string Default: application/json Value: "application/json" The content type that the client can understand. Writes only return a response body if they fail--for example, due to a formatting problem or quota limit.
Related guides |
| Content-Encoding | string Default: identity Enum: "gzip" "identity" The compression applied to the line protocol in the request payload.
To send a gzip payload, pass |
| Content-Length | integer The size of the entity-body, in bytes, sent to InfluxDB.
If the length is greater than the |
| Content-Type | string Default: text/plain; charset=utf-8 Enum: "text/plain" "text/plain; charset=utf-8" The format of the data in the request body.
To send a line protocol payload, pass |
| Zap-Trace-Span | string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context |
In the request body, provide data in line protocol format.
To send compressed data, do the following:
Content-Encoding: gzip header.airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630424257000000000 airSensors,sensor_id=TLM0202 temperature=75.30007505999716,humidity=35.651929918691714,co=0.5141876544505826 1630424257000000000
{- "code": "invalid",
- "message": "failed to parse line protocol: error writing line 2: Unable to insert iox::column_type::field::integer type into column temp with type iox::column_type::field::string"
}Writes data to a database.
Use this InfluxDB v1-compatible endpoint to send data in line protocol format to InfluxDB using v1 API parameters and authorization.
InfluxDB does the following when you send a write request:
204 status code), acknowledging that the data is written and queryable; error otherwise.To ensure that InfluxDB handles writes in the order you request them,
wait for a success response (HTTP 2xx status code) before you send the next request.
| db required | string database to write to. If none exists, InfluxDB creates a database with a default 3-day retention policy. |
| p | string The InfluxDB 1.x password to authenticate the request. |
| precision | string Write precision. |
| rp | string Retention policy name. |
| u | string The InfluxDB 1.x username to authenticate the request. |
| Content-Encoding | string Default: identity Enum: "gzip" "identity" When present, its value indicates to the database that compression is applied to the line protocol body. |
| Zap-Trace-Span | string Example: baggage,[object Object],span_id,1,trace_id,1 OpenTracing span context |
Line protocol body
{- "code": "invalid",
- "line": 2,
- "message": "no data written, errors encountered on line(s): error message for first rejected point</n> error message for second rejected point</n> error message for Nth rejected point (up to 100 rejected points)"
}