Write data

Download Cloud Dedicated Data API Spec
Write time series data to InfluxDB 3 Cloud Dedicated databases using the v2-compatible /api/v2/write endpoint or the v1-compatible /write endpoint with line protocol.
POST /api/v2/write

Write data using the InfluxDB v2 HTTP API

Writes data to a database.

Use this endpoint to send data in line protocol format to InfluxDB.

InfluxDB 3 Cloud Dedicated does the following when you send a write request:

  1. Validates the request.

  2. If successful, attempts to ingest data from the request body; otherwise, responds with an error status.

  3. 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.

Write endpoints

The /write and /api/v2/write endpoints are functionally equivalent for writing data to InfluxDB Cloud Dedicated.

Parameters

Query parameters
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.

bucket required string
A database name or ID. InfluxDB writes all points in the batch to the specified database.
precision string
The precision for unix timestamps in the line protocol batch.
Header parameters
Zap-Trace-Span string
OpenTracing span context
Content-Encoding string
The compression applied to the line protocol in the request payload. To send a gzip payload, pass Content-Encoding: gzip header.
Allowed values: gzip , identity
Default: identity
Content-Type string
The format of the data in the request body. To send a line protocol payload, pass Content-Type: text/plain; charset=utf-8.
Allowed values: text/plain , text/plain; charset=utf-8
Default: text/plain; charset=utf-8
Content-Length integer
The size of the entity-body, in bytes, sent to InfluxDB. If the length is greater than the max body configuration option, the server responds with status code 413.
Accept string

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

  • Returns only application/json for format and limit errors.
  • Returns only text/html for some quota limit errors.
Allowed values: application/json
Default: application/json

Request body required

In the request body, provide data in line protocol format.

To send compressed data, do the following:

  1. Use gzip to compress the line protocol data.
  2. In your request, send the compressed data and the Content-Encoding: gzip header.
Content-Type: application/json
Example request Ask AI about this
curl --request POST \
  "https://cluster-id.a.influxdb.io/api/v2/write?org=ORG&bucket=BUCKET" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: text/plain" \
  --data-raw 'airSensors,sensor_id=TLM0201 temperature=73.97038159354763,humidity=35.23103248356096,co=0.48445310567793615 1630424257000000000'

Responses

201 Success (“Created”). Some points in the batch are written and queryable, and some points are rejected. The response body contains details about the rejected points, up to 100 points.
code required string
Code is the machine-readable error code.
Allowed: internal error , not found , conflict , invalid , empty value , unavailable
err string
Stack of errors that occurred during processing of the request. Useful for debugging.
line integer <int32>
First line in the request body that contains malformed data.
message string
Human-readable message.
op string
Describes the logical code operation when the error occurred. Useful for debugging.
204 Success (“No Content”). All data in the batch is written and queryable.
400 All data in body was rejected and not written.
code required string
Code is the machine-readable error code.
Allowed: internal error , not found , conflict , invalid , empty value , unavailable
err string
Stack of errors that occurred during processing of the request. Useful for debugging.
line integer <int32>
First line in the request body that contains malformed data.
message string
Human-readable message.
op string
Describes the logical code operation when the error occurred. Useful for debugging.
401

Unauthorized. The error may indicate one of the following:

  • The Authorization: Token header is missing or malformed.
  • The API token value is missing from the header.
  • The token doesn’t have sufficient permissions to write to or query the database.
code string
The HTTP status code description. Default is unauthorized.
Allowed: unauthorized
message string
A human-readable message that may contain detail about the error.
404

Not found. A requested resource was not found. The response body contains the requested resource type and the name value (if you passed it)–for example:

  • "organization name \"my-org\" not found"
  • "organization not found": indicates you passed an ID that did not match an organization.
code required string
code is the machine-readable error code.
Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type
err string
Stack of errors that occurred during processing of the request. Useful for debugging.
message string
Human-readable message.
op string
Describes the logical code operation when the error occurred. Useful for debugging.
500 Internal server error. The server encountered an unexpected situation.
code required string
code is the machine-readable error code.
Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type
err string
Stack of errors that occurred during processing of the request. Useful for debugging.
message string
Human-readable message.
op string
Describes the logical code operation when the error occurred. Useful for debugging.
503

Service unavailable.

  • Returns this error if the server is temporarily unavailable to accept writes due to concurrent request limits or insufficient healthy ingesters.
default Non 2XX error response from server.
code required string
code is the machine-readable error code.
Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type
err string
Stack of errors that occurred during processing of the request. Useful for debugging.
message string
Human-readable message.
op string
Describes the logical code operation when the error occurred. Useful for debugging.
POST /write

Write data using the InfluxDB v1 HTTP API

Writes data to a database.

Use this endpoint for InfluxDB v1 parameter compatibility when sending data in line protocol format to InfluxDB.

InfluxDB 3 Cloud Dedicated does the following when you send a write request:

  1. Validates the request.

  2. If successful, attempts to ingest data from the request body; otherwise, responds with an error status.

  3. 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
    • 201 Created (If the cluster is configured to allow partial writes): some points in the batch are ingested and queryable, and some points are rejected
    • 400 Bad Request: all data is rejected

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.

Write endpoints

The /write and /api/v2/write endpoints are functionally equivalent for writing data to InfluxDB Cloud Dedicated.

Parameters

Query parameters
u string
The InfluxDB 1.x username to authenticate the request.
p string
The InfluxDB 1.x password to authenticate the request.
db required string
database to write to. If none exists, InfluxDB creates a database with a default 3-day retention policy.
rp string
Retention policy name.
precision string
Write precision.
Header parameters
Zap-Trace-Span string
OpenTracing span context
Content-Encoding string
When present, its value indicates to the database that compression is applied to the line protocol body.
Allowed values: gzip , identity
Default: identity

Request body required

Line protocol body
Content-Type: application/json
Example request Ask AI about this
curl --request POST \
  "https://cluster-id.a.influxdb.io/write?db=DB" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: text/plain" \
  --data-raw 'measurement,tag=value field=1.0'

Responses

204 Success (“No Content”). All data in the batch is written and queryable.
400

Data from the batch was rejected and not written. The response body indicates if a partial write occurred or all data was rejected. If a partial write occurred, then some points from the batch are written and queryable.

The response body contains details about the rejected points, up to 100 points.

code required string
Code is the machine-readable error code.
Allowed: internal error , not found , conflict , invalid , empty value , unavailable
err string
Stack of errors that occurred during processing of the request. Useful for debugging.
line integer <int32>
First line in the request body that contains malformed data.
message string
Human-readable message.
op string
Describes the logical code operation when the error occurred. Useful for debugging.
401 Token doesn’t have sufficient permissions to write to this database or the database doesn’t exist.
code required string
code is the machine-readable error code.
Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type
err string
Stack of errors that occurred during processing of the request. Useful for debugging.
message string
Human-readable message.
op string
Describes the logical code operation when the error occurred. Useful for debugging.
403 No token was sent and they are required.
code required string
code is the machine-readable error code.
Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type
err string
Stack of errors that occurred during processing of the request. Useful for debugging.
message string
Human-readable message.
op string
Describes the logical code operation when the error occurred. Useful for debugging.
413 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.
code required string
Code is the machine-readable error code.
Allowed: invalid
message required string
Human-readable message.
422

Unprocessable Entity.

The request contained data outside the database’s retention period. InfluxDB rejected the batch and wrote no data.

The response body contains details about the rejected points.

429 Token is temporarily over quota or ingesters are resource constrained.
503 Server is temporarily unavailable to accept writes due to too many concurrent requests or insufficient healthy ingesters.
default Internal server error
code required string
code is the machine-readable error code.
Allowed: internal error , not implemented , not found , conflict , invalid , unprocessable entity , empty value , unavailable , forbidden , too many requests , unauthorized , method not allowed , request too large , unsupported media type
err string
Stack of errors that occurred during processing of the request. Useful for debugging.
message string
Human-readable message.
op string
Describes the logical code operation when the error occurred. Useful for debugging.

Was this page helpful?

Thank you for your feedback!