Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 39 ยท Writing Data

Writing Data with the HTTP API

Write line protocol to InfluxDB 1.x, 2.x and 3.x over HTTP with curl: endpoints, authentication headers, gzip, response codes and which errors to retry.

Every InfluxDB write, whether it comes from the CLI, Telegraf or a client library, ends up as an HTTP POST carrying line protocol. Knowing the raw request helps you debug anything: a script that "does nothing", a 401 from a proxy, a partial write that loses a few lines. In this lesson you build the request by hand, learn the endpoints of each generation and decide how to react to each response status.

The curl commands need a live server and are read-only here. The runnable blocks are JavaScript stand-ins that build requests and classify responses, without any network access.

Anatomy of a write request

sequenceDiagram
  participant App
  participant InfluxDB
  App->>InfluxDB: POST /api/v2/write?org=o&bucket=b&precision=s
  Note right of App: Authorization: Token ...<br/>Content-Type: text/plain<br/>body = line protocol
  InfluxDB-->>App: 204 No Content

A write is a POST with a text body; success is 204 with no response body.

Endpoints by generation

Generation Endpoint Key parameters
1.x POST /write db, rp (retention policy), precision, u and p or a token
2.x POST /api/v2/write org, bucket, precision
3.x POST /api/v3/write_lp db, precision, accept_partial, no_sync

InfluxDB 3 also accepts the 1.x /write and 2.x /api/v2/write endpoints for compatibility, which makes it easy to keep existing Telegraf configs and client code during a migration.

A 2.x write with curl

Terminal
curl --request POST \
  "http://localhost:8086/api/v2/write?org=my-org&bucket=weather&precision=s" \
  --header "Authorization: Token $INFLUX_TOKEN" \
  --header "Content-Type: text/plain; charset=utf-8" \
  --data-binary '
weather,city=Lisbon temp=18.4,humidity=62i 1772359200
weather,city=Porto temp=15.1,humidity=70i 1772359200'

A 3.x write with curl

Terminal
curl --request POST \
  "http://localhost:8181/api/v3/write_lp?db=weather&precision=second" \
  --header "Authorization: Bearer $INFLUXDB3_AUTH_TOKEN" \
  --data-binary 'weather,city=Lisbon temp=18.4,humidity=62i 1772359200'

Two 3.x options are worth knowing. accept_partial (on by default) means that valid lines in a batch are written even if some lines are invalid, and the response describes the rejected lines. Setting it to false makes the batch all-or-nothing. no_sync returns before the data is durable on disk, which is faster but riskier; the default waits for durability.

Compression

Line protocol compresses very well (repeated keys). Add Content-Encoding: gzip and send a gzip body to cut bandwidth by 5 to 10 times:

Terminal
gzip -c points.lp | curl --request POST "http://localhost:8086/api/v2/write?org=my-org&bucket=weather&precision=s" \
  --header "Authorization: Token $INFLUX_TOKEN" \
  --header "Content-Encoding: gzip" \
  --data-binary @-

Response codes

Status Meaning What to do
204 Success Nothing
400 Bad request: malformed line protocol Fix the data; do not retry
401 Missing, wrong or expired token Fix credentials
403 Token lacks write permission for this bucket Fix permissions
404 Bucket, database or org not found Check names (a typo is common)
413 Request body too large Split the batch
422 Unprocessable: for example a field type conflict Fix the data; retrying cannot help
429 Too many requests Retry after the delay in Retry-After
500, 503 Server busy or unavailable Retry with exponential back-off

The rule: 4xx means your request is wrong (except 429); 5xx and 429 are temporary. A good client retries only the temporary ones, with growing delays and some randomness (jitter), and has a bound on how long it keeps trying.

JS Which responses should be retried? (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Building the request in code

The following stand-in assembles the URL, headers and body of a write request for either generation. It never sends anything; printing the request is a great way to compare with what a library produced when something goes wrong.

JS Assemble a write request (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Batch size

Single-point writes are slow: each one pays for an HTTP round trip and a durable write. Send batches of a few thousand lines (the documentation commonly suggests about 5,000, or up to roughly 10 MB uncompressed) per request. Too-large batches risk 413 errors and long retries on failure; too-small ones waste time. Measure with your own data (Batching and Write Errors goes deeper).

Checking what you wrote

After a write, query it back. With 3.x:

Terminal
curl --get "http://localhost:8181/api/v3/query_sql" \
  --header "Authorization: Bearer $INFLUXDB3_AUTH_TOKEN" \
  --data-urlencode "db=weather" \
  --data-urlencode "q=SELECT * FROM weather ORDER BY time DESC LIMIT 5" \
  --data-urlencode "format=json"

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which status code means a write succeeded?

    InfluxDB answers a successful write with 204 and an empty body.
  2. 2. A write returns 400 because of malformed line protocol. What should the client do?

    Client errors are permanent for that body; only 429 and 5xx are worth retrying.
  3. 3. What does the 2.x write endpoint need as query parameters?

    The 2.x write identifies the target with org and bucket and states the timestamp precision.
  4. 4. Why use Content-Encoding: gzip on writes?

    Repeated keys make line protocol compress very well.

Summary

  • A write is an HTTP POST of line protocol; 2.x uses /api/v2/write, 3.x /api/v3/write_lp, 1.x /write.
  • Authenticate with a token header; state the precision explicitly.
  • 204 is success; 4xx (except 429) are permanent, 429 and 5xx should be retried with back-off.
  • Compress and batch; check the result with a query.

Next: Batching and Write Errors