Data I/O endpoints

Download InfluxDB API Spec
POST /api/v2/delete

Delete data

Deletes data from a bucket.

Use this endpoint to delete points from a bucket in a specified time range.

InfluxDB Cloud

  • Does the following when you send a delete request:

    1. Validates the request and queues the delete.
    2. If queued, responds with success (HTTP 2xx status code); error otherwise.
    3. Handles the delete asynchronously and reaches eventual consistency.

To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a success response (HTTP 2xx status code) before you send the next request.

Because writes and deletes are asynchronous, your change might not yet be readable when you receive the response.

InfluxDB OSS

  • Validates the request, handles the delete synchronously, and then responds with success or failure.

Required permissions

  • write-buckets or write-bucket BUCKET_ID.

BUCKET_ID is the ID of the destination bucket.

Rate limits (with InfluxDB Cloud)

write rate limits apply. For more information, see limits and adjustable quotas.

Parameters

Query parameters
org string

An organization name or ID.

InfluxDB Cloud

  • Doesn’t use the org parameter or orgID parameter.
  • Deletes data from the bucket in the organization associated with the authorization (API token).

InfluxDB OSS

  • Requires either the org parameter or the orgID parameter.
  • Deletes data from the bucket in the specified organization.
  • If you pass both orgID and org, they must both be valid.
bucket string
A bucket name or ID. Specifies the bucket to delete data from. If you pass both bucket and bucketID, bucketID takes precedence.
orgID string

An organization ID.

InfluxDB Cloud

  • Doesn’t use the org parameter or orgID parameter.
  • Deletes data from the bucket in the organization associated with the authorization (API token).

InfluxDB OSS

  • Requires either the org parameter or the orgID parameter.
  • Deletes data from the bucket in the specified organization.
  • If you pass both orgID and org, they must both be valid.
bucketID string
A bucket ID. Specifies the bucket to delete data from. If you pass both bucket and bucketID, bucketID takes precedence.
Header parameters
Zap-Trace-Span string
OpenTracing span context

Request body required

Time range parameters and an optional delete predicate expression.

To select points to delete within the specified time range, pass a delete predicate expression in the predicate property of the request body. If you don’t pass a predicate, InfluxDB deletes all data with timestamps in the specified time range.

Content-Type: application/json
predicate string
An expression in delete predicate syntax.
Example: "tag1=\"value1\" and (tag2=\"value2\" and tag3!=\"value3\")"
start required string <date-time>
A timestamp (RFC3339 date/time format). The earliest time to delete from.
stop required string <date-time>
A timestamp (RFC3339 date/time format). The latest time to delete from.
Example request Ask AI about this
curl --request POST \
  "http://localhost:8086/api/v2/delete" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "predicate": "tag1=\"value1\" and (tag2=\"value2\" and tag3!=\"value3\")",
  "start": "START",
  "stop": "STOP"
}'

Responses

204

Success.

InfluxDB Cloud

  • Validated and queued the request.
  • Handles the delete asynchronously - the deletion might not have completed yet.

An HTTP 2xx status code acknowledges that the write or delete is queued. To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a response before you send the next request.

Because writes are asynchronous, data might not yet be written when you receive the response.

InfluxDB OSS

  • Deleted the data.
400

Bad request. The response body contains detail about the error.

InfluxDB OSS

  • Returns this error if the org parameter or orgID parameter doesn’t 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.
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 this organization and bucket.
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.
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 /api/v2/query

Query data

Retrieves data from buckets.

Use this endpoint to send a Flux query request and retrieve data from a bucket.

Rate limits (with InfluxDB Cloud)

read rate limits apply. For more information, see limits and adjustable quotas.

Parameters

Query parameters
org string

An organization name or ID.

InfluxDB Cloud

  • Doesn’t use the org parameter or orgID parameter.
  • Queries the bucket in the organization associated with the authorization (API token).

InfluxDB OSS

  • Requires either the org parameter or orgID parameter.
  • Queries the bucket in the specified organization.
orgID string

An organization ID.

InfluxDB Cloud

  • Doesn’t use the org parameter or orgID parameter.
  • Queries the bucket in the organization associated with the authorization (API token).

InfluxDB OSS

  • Requires either the org parameter or orgID parameter.
  • Queries the bucket in the specified organization.
Header parameters
Zap-Trace-Span string
OpenTracing span context
Accept-Encoding string
The content encoding (usually a compression algorithm) that the client can understand.
Allowed values: gzip , identity
Default: identity
Content-Type string
Allowed values: application/json , application/vnd.flux

Request body

Flux query or specification to execute
Content-Type: application/json
dialect string
extern string
now string <date-time>
Specifies the time that should be reported as now in the query. Default is the server now time.
params object

Key-value pairs passed as parameters during query execution.

To use parameters in your query, pass a query with params references (in dot notation)–for example:

  query: "from(bucket: params.mybucket)\
              |> range(start: params.rangeStart) |> limit(n:1)"

and pass params with the key-value pairs–for example:

  params: {
    "mybucket": "environment",
    "rangeStart": "-30d"
  }

During query execution, InfluxDB passes params to your script and substitutes the values.

Limitations

  • If you use params, you can’t use extern.
query required string
The query script to execute.
type string
The type of query. Must be “flux”.
Allowed: flux
Example request Ask AI about this
curl --request POST \
  "http://localhost:8086/api/v2/query" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "dialect": {},
  "extern": {},
  "now": "NOW",
  "params": {},
  "query": "QUERY",
  "type": "flux"
}'

Responses

200 Success. The response body contains query results.
400

Bad request. The response body contains detail about the error.

InfluxDB OSS

  • Returns this error if the org parameter or orgID parameter doesn’t 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.
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 this organization and bucket.
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.
429

InfluxDB Cloud:

  • returns this error if a read or write request exceeds your plan’s adjustable service quotas or if a delete request exceeds the maximum global limit
  • returns Retry-After header that describes when to try the write again.

InfluxDB OSS:

  • doesn’t return this error.
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.
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.
GET /api/v2/tasks

List tasks

Retrieves a list of tasks.

To limit which tasks are returned, pass query parameters in your request. If no query parameters are passed, InfluxDB returns all tasks up to the default limit.

Parameters

Query parameters
name string
A task name. Only returns tasks with the specified name. Different tasks may have the same name.
after string
A task ID. Only returns tasks created after the specified task.
user string
A user ID. Only returns tasks owned by the specified user.
org string
An organization name. Only returns tasks owned by the specified organization.
orgID string
An organization ID. Only returns tasks owned by the specified organization.
status string
A task status. Only returns tasks that have the specified status (active or inactive).
Allowed values: active , inactive
limit integer

The maximum number of tasks to return. Default is 100. The minimum is 1 and the maximum is 500.

To reduce the payload size, combine type=basic and limit (see Request samples). For more information about the basic response, see the type parameter.

Default: 100
type string
A task type (basic or system). Default is system. Specifies the level of detail for tasks in the response. The default (system) response contains all the metadata properties for tasks. To reduce the response size, pass basic to omit some task properties (flux, createdAt, updatedAt).
Allowed values: basic , system
Header parameters
Zap-Trace-Span string
OpenTracing span context
Example request Ask AI about this
curl --request GET \
  "http://localhost:8086/api/v2/tasks" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains the list of tasks.
links string
tasks object[]
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 this organization and bucket.
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.
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.
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 /api/v2/tasks

Create a task

Creates a task and returns the task.

Parameters

Header parameters
Zap-Trace-Span string
OpenTracing span context

Request body required

The task to create.
Content-Type: application/json
description string
An optional description of the task.
flux required string
The Flux script to run for this task.
org string
The name of the organization that owns this Task.
orgID string
The ID of the organization that owns this Task.
status string
Example request Ask AI about this
curl --request POST \
  "http://localhost:8086/api/v2/tasks" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "description": "DESCRIPTION",
  "flux": "FLUX",
  "org": "ORG",
  "orgID": "ORGID",
  "status": "active"
}'

Responses

201 Success. The response body contains a tasks list with the task.
authorizationID string

An authorization ID. Specifies the authorization used when the task communicates with the query engine.

To find an authorization ID, use the GET /api/v2/authorizations endpoint to list authorizations.

createdAt string <date-time>
cron string
A Cron expression that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.
description string
A description of the task.
every string <duration>
The interval (duration literal) at which the task runs. every also determines when the task first runs, depending on the specified time.
flux required string <flux>
The Flux script that the task executes.
id required string
labels string
lastRunError string
lastRunStatus string
Allowed: failed , success , canceled
latestCompleted string <date-time>
A timestamp (RFC3339 date/time format) of the latest scheduled and completed run.
links object
Example: {"labels":"/api/v2/tasks/1/labels","logs":"/api/v2/tasks/1/logs","members":"/api/v2/tasks/1/members","owners":"/api/v2/tasks/1/owners","runs":"/api/v2/tasks/1/runs","self":"/api/v2/tasks/1"}
labels string
logs string
members string
owners string
runs string
self string
name required string
The name of the task.
offset string <duration>
A duration to delay execution of the task after the scheduled time has elapsed. 0 removes the offset.
org string
An organization name. Specifies the organization that owns the task.
orgID required string
An organization ID. Specifies the organization that owns the task.
ownerID string

A user ID. Specifies the owner of the task.

To find a user ID, you can use the GET /api/v2/users endpoint to list users.

status string
updatedAt string <date-time>
400

Bad request. The response body contains detail about the error.

InfluxDB OSS

  • Returns this error if an incorrect value is passed for org or orgID.
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.
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 this organization and bucket.
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.
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.
default Unexpected 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.
GET /api/v2/tasks/{taskID}

Retrieve a task

Retrieves a task.

Parameters

Path parameters
taskID required string
The ID of the task to retrieve.
Header parameters
Zap-Trace-Span string
OpenTracing span context
Example request Ask AI about this
curl --request GET \
  "http://localhost:8086/api/v2/tasks/{taskID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains the task.
authorizationID string

An authorization ID. Specifies the authorization used when the task communicates with the query engine.

To find an authorization ID, use the GET /api/v2/authorizations endpoint to list authorizations.

createdAt string <date-time>
cron string
A Cron expression that defines the schedule on which the task runs. InfluxDB uses the system time when evaluating Cron expressions.
description string
A description of the task.
every string <duration>
The interval (duration literal) at which the task runs. every also determines when the task first runs, depending on the specified time.
flux required string <flux>
The Flux script that the task executes.
id required string
labels string
lastRunError string
lastRunStatus string
Allowed: failed , success , canceled
latestCompleted string <date-time>
A timestamp (RFC3339 date/time format) of the latest scheduled and completed run.
links object
Example: {"labels":"/api/v2/tasks/1/labels","logs":"/api/v2/tasks/1/logs","members":"/api/v2/tasks/1/members","owners":"/api/v2/tasks/1/owners","runs":"/api/v2/tasks/1/runs","self":"/api/v2/tasks/1"}
labels string
logs string
members string
owners string
runs string
self string
name required string
The name of the task.
offset string <duration>
A duration to delay execution of the task after the scheduled time has elapsed. 0 removes the offset.
org string
An organization name. Specifies the organization that owns the task.
orgID required string
An organization ID. Specifies the organization that owns the task.
ownerID string

A user ID. Specifies the owner of the task.

To find a user ID, you can use the GET /api/v2/users endpoint to list users.

status string
updatedAt string <date-time>
400

Bad request. The response body contains detail about the error.

InfluxDB OSS

  • Returns this error if an incorrect value is passed in the org parameter or orgID parameter.
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.
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 this organization and bucket.
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.
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 /api/v2/tasks/{taskID}/runs

Start a task run, overriding the schedule

Schedules a task run to start immediately, ignoring scheduled runs.

Use this endpoint to manually start a task run. Scheduled runs will continue to run as scheduled. This may result in concurrently running tasks.

To retry a previous run (and avoid creating a new run), use the POST /api/v2/tasks/{taskID}/runs/{runID}/retry endpoint.

Parameters

Path parameters
taskID required string
Header parameters
Zap-Trace-Span string
OpenTracing span context

Request body

Content-Type: application/json
scheduledFor string <date-time>
The time RFC3339 date/time format used for the run’s now option. Default is the server now time.
Example request Ask AI about this
curl --request POST \
  "http://localhost:8086/api/v2/tasks/{taskID}/runs" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "scheduledFor": "SCHEDULEDFOR"
}'

Responses

201 Success. The run is scheduled to start.
finishedAt string <date-time>
The time (RFC3339Nano date/time format) the run finished executing.
Example: "2006-01-02T15:04:05.999999999Z07:00"
flux string
Flux used for the task
id string
links object
Example: {"retry":"/api/v2/tasks/1/runs/1/retry","self":"/api/v2/tasks/1/runs/1","task":"/api/v2/tasks/1"}
retry string <uri>
self string <uri>
task string <uri>
log object[]
An array of logs associated with the run.
requestedAt string <date-time>
The time (RFC3339Nano date/time format) the run was manually requested.
Example: "2006-01-02T15:04:05.999999999Z07:00"
scheduledFor string <date-time>
The time RFC3339 date/time format used for the run’s now option.
startedAt string <date-time>
The time (RFC3339Nano date/time format) the run started executing.
Example: "2006-01-02T15:04:05.999999999Z07:00"
status string
Allowed: scheduled , started , failed , success , canceled
taskID string
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 this organization and bucket.
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.
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.
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 /api/v2/write

Write data

Writes data to a bucket.

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

InfluxDB Cloud

  • Does the following when you send a write request:

    1. Validates the request and queues the write.
    2. If queued, responds with success (HTTP 2xx status code); error otherwise.
    3. Handles the delete asynchronously and reaches eventual consistency.

    To ensure that InfluxDB Cloud handles writes and deletes in the order you request them, wait for a success response (HTTP 2xx status code) before you send the next request.

    Because writes and deletes are asynchronous, your change might not yet be readable when you receive the response.

InfluxDB OSS

  • Validates the request and handles the write synchronously.
  • If all points were written successfully, responds with HTTP 2xx status code; otherwise, returns the first line that failed.

Required permissions

  • write-buckets or write-bucket BUCKET_ID.

BUCKET_ID is the ID of the destination bucket.

Rate limits (with InfluxDB Cloud)

write rate limits apply. For more information, see limits and adjustable quotas.

Parameters

Query parameters
org required string

An organization name or ID.

InfluxDB Cloud

  • Doesn’t use the org parameter or orgID parameter.
  • Writes data to the bucket in the organization associated with the authorization (API token).

InfluxDB OSS

  • Requires either the org parameter or the orgID parameter.
  • If you pass both orgID and org, they must both be valid.
  • Writes data to the bucket in the specified organization.
orgID string

An organization ID.

InfluxDB Cloud

  • Doesn’t use the org parameter or orgID parameter.
  • Writes data to the bucket in the organization associated with the authorization (API token).

InfluxDB OSS

  • Requires either the org parameter or the orgID parameter.
  • If you pass both orgID and org, they must both be valid.
  • Writes data to the bucket in the specified organization.
bucket required string
A bucket name or ID. InfluxDB writes all points in the batch to the specified bucket.
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.

InfluxDB OSS

  • Returns only application/json for format and 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 \
  "http://localhost:8086/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

204

Success.

InfluxDB Cloud

  • Validated and queued the request.
  • Handles the write asynchronously - the write might not have completed yet.

InfluxDB OSS

  • Successfully wrote all points in the batch.
400

Bad request. The response body contains detail about the error.

InfluxDB returns this error if the line protocol data in the request is malformed. The response body contains the first malformed line in the data, and indicates what was expected. For partial writes, the number of points written and the number of points rejected are also included. For more information, check the rejected_points measurement in your _monitoring bucket.

InfluxDB Cloud

  • Returns this error for bucket schema conflicts.

InfluxDB OSS

  • Returns this error if the org parameter or orgID parameter doesn’t match an organization.
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 this organization and bucket.
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.
413

The request payload is too large. InfluxDB rejected the batch and did not write any data.

InfluxDB Cloud:

  • Returns this error if the payload exceeds the 50MB size limit.
  • Returns Content-Type: text/html for this error.

InfluxDB OSS:

code required string
Code is the machine-readable error code.
Allowed: invalid
message required string
Human-readable message.
429

Too many requests.

InfluxDB Cloud

  • Returns this error if a read or write request exceeds your plan’s adjustable service quotas or if a delete request exceeds the maximum global limit.
  • For rate limits that reset automatically, returns a Retry-After header that describes when to try the write again.
  • For limits that can’t reset (for example, cardinality limit), doesn’t return a Retry-After header.

Rates (data-in (writes), queries (reads), and deletes) accrue within a fixed five-minute window. Once a rate limit is exceeded, InfluxDB returns an error response until the current five-minute window resets.

InfluxDB OSS

  • Doesn’t return this error.
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.
  • Returns a Retry-After header that describes when to try the write again.
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.

Was this page helpful?

Thank you for your feedback!