The InfluxDB v2 HTTP API for InfluxDB Cloud Dedicated provides a v2-compatible programmatic interface for writing data stored in an InfluxDB Cloud Dedicated 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.
InfluxDB Cloud Dedicated provides the following HTTP API endpoints for writing data:
/api/v2/write endpoint for new write workloads or for bringing existing InfluxDB v2 write workloads to v3./write endpoint for bringing existing InfluxDB v1 write workloads to v3.Both endpoints accept the same line protocol format and process data in the same way.
InfluxDB Cloud Dedicated provides the following protocols for executing a query:
/query request that contains an InfluxQL query.
Use this protocol when bringing existing InfluxDB v1 query workloads to v3.The HTTP API /api/v2/write endpoint works with the Bearer and Token authentication schemes and existing InfluxDB 2.x tools and code for writing data.
See how to use the InfluxDB v2 HTTP API with InfluxDB Cloud Dedicated.
The HTTP API /write endpoint and /query endpoint work with InfluxDB 1.x username/password authentication schemes and existing InfluxDB 1.x tools and code.
See how to use the InfluxDB v1 HTTP API with InfluxDB Cloud Dedicated.
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 Cloud Dedicated checks that the password part of the decoded credential is an authorized database token.
InfluxDB Cloud Dedicated 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 Cloud Dedicated).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 Cloud Dedicated 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 Cloud Dedicated 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 Cloud Dedicated 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 | |
201 | Created | One or more resources are created. The response body contains details about the resource. |
204 | No content | The request is successful and no data is returned. For example, The /write and /api/v2/write endpoints return this status code if all data in the batch is written and queryable. |
400 | Bad request | InfluxDB can't parse the request due to an incorrect parameter or bad syntax. For writes, the error may indicate one of the following problems:
|
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. |
422 | Unprocessable entity | Request data is invalid. code and message in the response body provide details about the problem. |
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. |
Reports the InfluxQL bridge querier health and the InfluxDB version of the instance.
The response is a HTTP 204 status code to inform you the querier is available.
For InfluxDB Cloud Dedicated, this endpoint only checks the status of queriers; doesn't check the status of ingesters.
To check the health of ingesters before writing data, send a request to one of the write endpoints.
This endpoint doesn't require authentication.
Reports the InfluxQL bridge querier health and the InfluxDB version of the instance.
The response is a HTTP 204 status code to inform you the querier is available.
For InfluxDB Cloud Dedicated, this endpoint only checks the status of queriers; doesn't check the status of ingesters.
To check the health of ingesters before writing data, send a request to one of the write endpoints.
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 Cloud Dedicated.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 Cloud Dedicated does the following when you send a write request:
Validates the request.
If successful, attempts to ingest data from the request body; otherwise, responds with an error status.
Ingests or rejects data in the batch and returns one of the following HTTP status codes:
204 No Content: All data in the batch is ingested.400 Bad Request: Some (when partial writes are configured for the cluster) or all of the data has been rejected. Data that has not been rejected is ingested and queryable.The response body contains error details about rejected points, up to 100 points.
Writes are synchronous--the response status indicates the final status of the write and all ingested data is queryable.
To ensure that InfluxDB handles writes in the order you request them, wait for the response before you send the next request.
The /write and /api/v2/write endpoints are functionally equivalent for writing data to InfluxDB Cloud Dedicated.
/write endpoint for InfluxDB v1 parameter compatibility./api/v2/write endpoint for InfluxDB v2 parameter compatibility.| 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. InfluxDB Cloud
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",
- "line": 2,
- "message": "failed to parse line protocol: 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)"
}Writes data to a database.
Use this endpoint for InfluxDB v1 parameter compatibility when sending data in line protocol format to InfluxDB.
InfluxDB Cloud Dedicated does the following when you send a write request:
Validates the request.
If successful, attempts to ingest data from the request body; otherwise, responds with an error status.
Ingests or rejects data in the batch and returns one of the following HTTP status codes:
204 No Content: all data in the batch is ingested201 Created (If the cluster is configured to allow partial writes): some points in the batch are ingested and queryable, and some points are rejected400 Bad Request: all data is rejectedThe response body contains error details about rejected points, up to 100 points.
Writes are synchronous--the response status indicates the final status of the write and all ingested data is queryable.
To ensure that InfluxDB handles writes in the order you request them, wait for the response before you send the next request.
The /write and /api/v2/write endpoints are functionally equivalent for writing data to InfluxDB Cloud Dedicated.
/write endpoint for InfluxDB v1 parameter compatibility./api/v2/write endpoint for InfluxDB v2 parameter compatibility.| 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)"
}