openapi: 3.0.0 info: title: InfluxDB v1 HTTP API for InfluxDB 3 Clustered version: '' description: | The InfluxDB v1 HTTP API provides v1 compatibility for writing and querying data in an InfluxDB 3 Clustered database. The InfluxDB 1.x `/write` and `/query` endpoints work with InfluxDB 1.x client libraries and third-party integrations like Grafana and others. This documentation is generated from the [InfluxDB OpenAPI specification](https://raw.githubusercontent.com/influxdata/openapi/master/contracts/swaggerV1Compat.yml). #### Related [InfluxDB `/api/v2` API for InfluxDB 3 Clustered](/influxdb3/clustered/api/v2/) license: name: MIT url: https://opensource.org/licenses/MIT contact: name: InfluxData url: https://www.influxdata.com email: support@influxdata.com servers: - url: / security: - TokenAuthentication: [] - BasicAuthentication: [] - QuerystringAuthentication: [] tags: - name: Authentication description: | The InfluxDB 1.x API requires authentication for all requests. InfluxDB Cloud uses InfluxDB API tokens to authenticate requests. For more information, see the following: - [Token authentication](#section/Authentication/TokenAuthentication) - [Basic authentication](#section/Authentication/BasicAuthentication) - [Querystring authentication](#section/Authentication/QuerystringAuthentication) x-traitTag: true - name: Query - name: Write paths: /write: post: operationId: PostWriteV1 tags: - Write summary: Write time series data into InfluxDB in a V1-compatible format requestBody: description: Line protocol body required: true content: text/plain: schema: type: string parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/AuthUserV1' - $ref: '#/components/parameters/AuthPassV1' - in: query name: db schema: type: string required: true description: | The database to write to. **Database targeting:** In InfluxDB Clustered, databases can be named using the `database_name/retention_policy_name` convention for InfluxQL compatibility. InfluxDB Clustered does not use DBRP mappings. The db and rp parameters are used to construct the target database name following this naming convention. **Auto-creation behavior:** InfluxDB Clustered requires databases to be created before writing data. The v1 `/write` API does not automatically create databases. If the specified database does not exist, the write request will fail. Authentication: Requires a valid API token with _write_ permissions for the target database. ### Related - [Write data to InfluxDB Clustered](/influxdb3/clustered/write-data/) - [Use the InfluxDB v1 API with InfluxDB Clustered](/influxdb3/clustered/guides/api-compatibility/v1/) - [Manage databases in InfluxDB Clustered](/influxdb3/clustered/admin/databases/) - [InfluxQL DBRP naming convention in InfluxDB Clustered](/influxdb3/clustered/admin/databases/create/#influxql-dbrp-naming-convention) - [Migrate data from InfluxDB v1 to InfluxDB Clustered](/influxdb3/clustered/guides/migrate-data/migrate-1x-to-clustered/) - in: query name: rp schema: type: string description: Retention policy name. - in: query name: precision schema: type: string description: Write precision. - in: header name: Content-Encoding description: When present, its value indicates to the database that compression is applied to the line protocol body. schema: type: string description: Specifies that the line protocol in the body is encoded with gzip or not encoded with identity. default: identity enum: - gzip - identity responses: '204': description: Write data is correctly formatted and accepted for writing to the bucket. '400': description: Line protocol poorly formed and no points were written. Response can be used to determine the first malformed line in the body line-protocol. All data in body was rejected and not written. content: application/json: schema: $ref: '#/components/schemas/LineProtocolError' '401': description: Token does not have sufficient permissions to write to this organization and bucket or the organization and bucket do not exist. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: No token was sent and they are required. content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: Write has been rejected because the payload is too large. Error message returns max size supported. All data in body was rejected and not written. content: application/json: schema: $ref: '#/components/schemas/LineProtocolLengthError' '429': description: Token is temporarily over quota. The Retry-After header describes when to try the write again. headers: Retry-After: description: A non-negative decimal integer indicating the seconds to delay after the response is received. schema: type: integer format: int32 '503': description: Server is temporarily unavailable to accept writes. The Retry-After header describes when to try the write again. headers: Retry-After: description: A non-negative decimal integer indicating the seconds to delay after the response is received. schema: type: integer format: int32 default: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' /query: get: operationId: GetQueryV1 tags: - Query summary: Query using the InfluxDB v1 HTTP API parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/AuthUserV1' - $ref: '#/components/parameters/AuthPassV1' - in: header name: Accept schema: type: string description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps. default: application/json enum: - application/json - application/csv - text/csv - application/x-msgpack - in: header name: Accept-Encoding description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand. schema: type: string description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity. default: identity enum: - gzip - identity - in: query name: chunked description: | If true, the response is divided into chunks of size `chunk_size`. schema: type: boolean default: false - in: query name: chunk_size description: | The number of records that will go into a chunk. This parameter is only used if `chunked=true`. schema: type: integer default: 10000 - in: query name: db schema: type: string required: true description: The database to query from. - in: query name: pretty description: | If true, the JSON response is formatted in a human-readable format. schema: type: boolean default: false - in: query name: q description: Defines the InfluxQL query to run. required: true schema: type: string - in: query name: rp schema: type: string description: Retention policy name. - name: epoch description: | Formats timestamps as unix (epoch) timestamps with the specified precision instead of RFC3339 timestamps with nanosecond precision. in: query schema: type: string enum: - h - m - s - ms - u - µ - ns responses: '200': description: Query results headers: Content-Encoding: description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body schema: type: string description: Specifies that the response in the body is encoded with gzip or not encoded with identity. default: identity enum: - gzip - identity Trace-Id: description: The Trace-Id header reports the request's trace ID, if one was generated. schema: type: string description: Specifies the request's trace ID. content: application/csv: schema: $ref: '#/components/schemas/InfluxQLCSVResponse' text/csv: schema: $ref: '#/components/schemas/InfluxQLCSVResponse' application/json: schema: $ref: '#/components/schemas/InfluxQLResponse' examples: influxql-chunk_size_2: value: | {"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:55Z",90,"1"],["2016-05-19T18:37:56Z",90,"1"]],"partial":true}],"partial":true}]} {"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:57Z",90,"1"],["2016-05-19T18:37:58Z",90,"1"]]}]}]} application/x-msgpack: schema: type: string format: binary '429': description: Token is temporarily over quota. The Retry-After header describes when to try the read again. headers: Retry-After: description: A non-negative decimal integer indicating the seconds to delay after the response is received. schema: type: integer format: int32 default: description: Error processing query content: application/json: schema: $ref: '#/components/schemas/Error' post: operationId: PostQueryV1 tags: - Query summary: Query using the InfluxDB v1 HTTP API requestBody: description: InfluxQL query to execute. content: text/plain: schema: type: string application/json: schema: type: object properties: db: type: string description: Database to query. rp: description: | The retention policy name for InfluxQL compatibility Optional parameter that, when combined with the db parameter, forms the complete database name to query. In InfluxDB Clustered, databases can be named using the database_name/retention_policy_name convention for InfluxQL compatibility. When a request specifies both `db` and `rp`, InfluxDB Clustered combines them as `db/rp` to target the database--for example: - If `db=mydb` and `rp=autogen`, the query targets the database named `mydb/autogen` - If only `db=mydb` is provided (no `rp`), the query targets the database named `mydb` Unlike InfluxDB v1 and Cloud Serverless, InfluxDB Clustered does not use DBRP mappings or separate retention policy objects. This parameter exists solely for v1 API compatibility and database naming conventions. Note: The retention policy name does not control data retention in InfluxDB Clustered. Data retention is determined by the database's _retention period_ setting. ### Related - [Use the v1 query API and InfluxQL to query data in InfluxDB Clustered](/influxdb3/clustered/query-data/execute-queries/influxdb-v1-api/) - [Use the InfluxDB v1 API with InfluxDB Clustered](/influxdb3/clustered/guides/api-compatibility/v1/) - [Manage databases in InfluxDB Clustered](/influxdb3/clustered/admin/databases/) - [InfluxQL DBRP naming convention in InfluxDB Clustered](/influxdb3/clustered/admin/databases/create/#influxql-dbrp-naming-convention) - [Migrate data from InfluxDB v1 to InfluxDB Clustered](/influxdb3/clustered/guides/migrate-data/migrate-1x-to-clustered/) type: string q: description: | Defines the InfluxQL query to run. type: string chunked: description: | If true, the response is divided into chunks of size `chunk_size`. type: boolean chunk_size: description: | The number of records that will go into a chunk. This parameter is only used if `chunked=true`. type: integer default: 10000 epoch: description: | A unix timestamp precision. type: string enum: - h - m - s - ms - u - µ - ns parameters: - $ref: '#/components/parameters/TraceSpan' - $ref: '#/components/parameters/AuthUserV1' - $ref: '#/components/parameters/AuthPassV1' - in: header name: Accept schema: type: string description: Specifies how query results should be encoded in the response. **Note:** With `application/csv`, query results include epoch timestamps instead of RFC3339 timestamps. default: application/json enum: - application/json - application/csv - text/csv - application/x-msgpack - in: header name: Accept-Encoding description: The Accept-Encoding request HTTP header advertises which content encoding, usually a compression algorithm, the client is able to understand. schema: type: string description: Specifies that the query response in the body should be encoded with gzip or not encoded with identity. default: identity enum: - gzip - identity - in: header name: Content-Type schema: type: string enum: - application/vnd.influxql - in: query name: db schema: type: string required: true description: Bucket to query. - in: query name: rp schema: type: string description: Retention policy name. - in: query name: q description: Defines the influxql query to run. schema: type: string responses: '200': description: Query results headers: Content-Encoding: description: The Content-Encoding entity header is used to compress the media-type. When present, its value indicates which encodings were applied to the entity-body schema: type: string description: Specifies that the response in the body is encoded with gzip or not encoded with identity. default: identity enum: - gzip - identity Trace-Id: description: The Trace-Id header reports the request's trace ID, if one was generated. schema: type: string description: Specifies the request's trace ID. content: application/csv: schema: $ref: '#/components/schemas/InfluxQLCSVResponse' text/csv: schema: $ref: '#/components/schemas/InfluxQLCSVResponse' application/json: schema: $ref: '#/components/schemas/InfluxQLResponse' examples: influxql-chunk_size_2: value: | {"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:55Z",90,"1"],["2016-05-19T18:37:56Z",90,"1"]],"partial":true}],"partial":true}]} {"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag"],"values":[["2016-05-19T18:37:57Z",90,"1"],["2016-05-19T18:37:58Z",90,"1"]]}]}]} application/x-msgpack: schema: type: string format: binary '429': description: Token is temporarily over quota. The Retry-After header describes when to try the read again. headers: Retry-After: description: A non-negative decimal integer indicating the seconds to delay after the response is received. schema: type: integer format: int32 default: description: Error processing query content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: TraceSpan: in: header name: Zap-Trace-Span description: OpenTracing span context example: trace_id: '1' span_id: '1' baggage: key: value required: false schema: type: string AuthUserV1: in: query name: u required: false schema: type: string description: Username. AuthPassV1: in: query name: p required: false schema: type: string description: User token. schemas: InfluxQLResponse: description: | The JSON response for an InfluxQL query. A response contains the collection of results for a query. `results` is an array of resultset objects. If the response is chunked, the `transfer-encoding` response header is set to `chunked` and each resultset object is sent in a separate JSON object. properties: results: description: | A resultset object that contains the `statement_id` and the `series` array. Except for `statement_id`, all properties are optional and omitted if empty. If a property is not present, it is assumed to be `null`. items: properties: error: type: string partial: description: | True if the resultset is not complete--the response data is chunked; otherwise, false or omitted. type: boolean series: description: | An array of series objects--the results of the query. A series of rows shares the same group key returned from the execution of a statement. If a property is not present, it is assumed to be `null`. items: properties: columns: description: An array of column names items: type: string type: array name: description: The name of the series type: string partial: description: | True if the series is not complete--the response data is chunked; otherwise, false or omitted. type: boolean tags: additionalProperties: type: string description: | A map of tag key-value pairs. If a tag key is not present, it is assumed to be `null`. type: object values: description: | An array of rows, where each row is an array of values. items: items: {} type: array type: array type: object type: array statement_id: description: | An integer that represents the statement's position in the query. If statement results are buffered in memory, `statement_id` is used to combine statement results. type: integer type: object oneOf: - required: - statement_id - error - required: - statement_id - series type: array type: object InfluxQLCSVResponse: type: string example: | name,tags,time,test_field,test_tag test_measurement,,1603740794286107366,1,tag_value test_measurement,,1603740870053205649,2,tag_value test_measurement,,1603741221085428881,3,tag_value Error: properties: code: description: Code is the machine-readable error code. readOnly: true type: string enum: - internal error - not found - conflict - invalid - unprocessable entity - empty value - unavailable - forbidden - too many requests - unauthorized - method not allowed message: readOnly: true description: Message is a human-readable message. type: string required: - code - message LineProtocolError: properties: code: description: Code is the machine-readable error code. readOnly: true type: string enum: - internal error - not found - conflict - invalid - empty value - unavailable message: readOnly: true description: Message is a human-readable message. type: string op: readOnly: true description: Op describes the logical code operation during error. Useful for debugging. type: string err: readOnly: true description: Err is a stack of errors that occurred during processing of the request. Useful for debugging. type: string line: readOnly: true description: First line within sent body containing malformed data type: integer format: int32 required: - code - message - op - err LineProtocolLengthError: properties: code: description: Code is the machine-readable error code. readOnly: true type: string enum: - invalid message: readOnly: true description: Message is a human-readable message. type: string maxLength: readOnly: true description: Max length in bytes for a body of line-protocol. type: integer format: int32 required: - code - message - maxLength securitySchemes: TokenAuthentication: type: apiKey name: Authorization in: header description: | Use the [Token authentication](#section/Authentication/TokenAuthentication) 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 an InfluxDB API token. The word `Token` is case-sensitive. ### Syntax `Authorization: Token YOUR_INFLUX_TOKEN` For examples and more information, see the following: - [`/authorizations`](#tag/Authorizations) endpoint. - [Authorize API requests](/influxdb/cloud/api-guide/api_intro/#authentication). - [Manage API tokens](/influxdb/cloud/security/tokens/). BasicAuthentication: type: http scheme: basic description: | Use the HTTP [Basic authentication](#section/Authentication/BasicAuthentication) scheme with clients that support the InfluxDB 1.x convention of username and password (that don't support the `Authorization: Token` scheme): For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/). QuerystringAuthentication: type: apiKey in: query name: u=&p= description: | Use the [Querystring authentication](#section/Authentication/QuerystringAuthentication) scheme with InfluxDB 1.x API parameters to provide credentials through the query string. For examples and more information, see how to [authenticate with a username and password](/influxdb/cloud/reference/api/influxdb-1x/).