Server information

Download InfluxDB 3 Enterprise API Spec
Retrieve server metrics, health status, and version information for InfluxDB 3 Enterprise.
GET /api/v3/configure/query_concurrency_limit

Get the query concurrency limit

Returns the current runtime limit on the maximum number of queries that can run concurrently. When the limit is set to the maximum allowed value, maxConcurrentQueries is omitted from the response.

This endpoint is only available in InfluxDB 3 Enterprise.

Example request Ask AI about this
curl --request GET \
  "https://localhost:8181/api/v3/configure/query_concurrency_limit" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. Returns the current query concurrency limit.
max_concurrent_queries integer
The maximum number of queries that can run concurrently. Omitted when the limit is set to the maximum allowed value.
Example request body
{
  "max_concurrent_queries": 32
}
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
PUT /api/v3/configure/query_concurrency_limit

Set the query concurrency limit

Sets the runtime limit on the maximum number of queries that can run concurrently. Omit max_concurrent_queries (or set it to null) to restore the limit configured at server startup.

Values below 16 are rejected unless force=true is set in the query string. A value of 0 is invalid, and values above the maximum allowed limit are rejected.

This endpoint is only available in InfluxDB 3 Enterprise.

Parameters

Query parameters
force boolean
Set to true to allow setting max_concurrent_queries to a value below the minimum of 16.

Request body required

Content-Type: application/json
max_concurrent_queries integer
The maximum number of queries that can run concurrently. Set to null (or omit) to restore the limit configured at server startup. Must be a positive integer; values below 16 require force=true.
Example request body
{
  "max_concurrent_queries": 32
}
Example request Ask AI about this
curl --request PUT \
  "https://localhost:8181/api/v3/configure/query_concurrency_limit" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"max_concurrent_queries":32}'

Responses

204 No content. The query concurrency limit was updated.
400

Request failed. Possible reasons:

  • Invalid database name
  • Malformed request body
  • Invalid timestamp precision
data object
error string
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
DELETE /api/v3/configure/query_concurrency_limit

Reset the query concurrency limit

Resets the runtime query concurrency limit to the value configured at server startup.

This endpoint is only available in InfluxDB 3 Enterprise.

Example request Ask AI about this
curl --request DELETE \
  "https://localhost:8181/api/v3/configure/query_concurrency_limit" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

204 No content. The query concurrency limit was reset.
401 Unauthorized access.
data object
error string
403 Access denied.
data object
error string
POST /api/v3/enterprise/configure/node/remove

Permanently remove a stopped node

Permanently removes a node that has already been marked as stopped, deleting its data from object storage once the compactor finishes reassigning its work.

This endpoint is only available in InfluxDB 3 Enterprise.

Request body required

Content-Type: application/json
force_finalize boolean
Force-finalize a node stuck in the Stopping state (for example, after a crash that never acknowledged the stop). This can delete unsnapshotted WAL data for that node — only use it when the node’s process is confirmed gone and you accept the data-loss risk.
node_id required string
The ID of the node to remove.
Example request body
{
  "node_id": "node-1"
}
Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/api/v3/enterprise/configure/node/remove" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"node_id":"node-1"}'

Responses

200 Success. The node has been removed.
400

Request failed. Possible reasons:

  • Invalid database name
  • Malformed request body
  • Invalid timestamp precision
data object
error string
401 Unauthorized access.
data object
error string
404 Node not found.
409 The node is not in a state that allows removal (for example, still running).
POST /api/v3/enterprise/configure/node/stop

Mark a node as stopped

Marks a node as stopped in the catalog, freeing up the licensed cores it was using for other nodes.

Use this endpoint after you have already stopped the physical instance (for example, using kill or stopping the container). This endpoint does not shut down the running process — you must stop the instance first.

When the node is marked as stopped:

  1. Licensed cores from the stopped node are freed for reuse
  2. Other nodes in the cluster see the update after their catalog sync interval

This endpoint is only available in InfluxDB 3 Enterprise.

Request body required

Content-Type: application/json
node_id required string
The ID of the node to mark as stopped.
Example request body
{
  "node_id": "node-1"
}
Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/api/v3/enterprise/configure/node/stop" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"node_id":"node-1"}'

Responses

200 Success. The node has been marked as stopped.
401 Unauthorized access.
data object
error string
404 Node not found.
GET /api/v3/enterprise/upgrade/parquet_cleanup

Get Parquet cleanup status

Returns the current or most recent Parquet cleanup state for the cluster.

This endpoint is only available in InfluxDB 3 Enterprise.

Example request Ask AI about this
curl --request GET \
  "https://localhost:8181/api/v3/enterprise/upgrade/parquet_cleanup" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. Returns the current Parquet cleanup state.
bytes_deleted required integer <int64>
Total size, in bytes, of the deleted files. Always 0 in dry_run mode.
bytes_matched required integer <int64>
Total size, in bytes, of the matched files.
completed_at_ns integer <int64>
When the cleanup finished, in nanoseconds since the Unix epoch.
files_deleted required integer <int64>
Number of files deleted so far. Always 0 in dry_run mode.
files_failed required integer <int64>
Number of files the cleanup failed to delete.
files_matched required integer <int64>
Number of files identified as Parquet-era data to delete.
files_scanned required integer <int64>
Number of files the cleanup has scanned so far.
last_message string
The most recent human-readable status message, if any.
mode required string
Whether this cleanup deletes data or only reports what it would delete.
Allowed: delete , dry_run
requested_at_ns integer <int64>
When the cleanup was requested, in nanoseconds since the Unix epoch.
requested_by string
The node that accepted the cleanup request, if recorded.
started_at_ns integer <int64>
When the cleanup started running, in nanoseconds since the Unix epoch.
status required string
The cleanup’s current status.
Allowed: requested , running , completed , failed
updated_at_ns integer <int64>
When this status was last updated, in nanoseconds since the Unix epoch.
Example request body
{
  "bytes_deleted": 4294967296,
  "bytes_matched": 4294967296,
  "completed_at_ns": 1735689900000000000,
  "files_deleted": 812,
  "files_failed": 0,
  "files_matched": 812,
  "files_scanned": 1024,
  "last_message": null,
  "mode": "delete",
  "requested_at_ns": 1735689600000000000,
  "requested_by": "node-1",
  "started_at_ns": 1735689601000000000,
  "status": "completed",
  "updated_at_ns": 1735689900000000000
}
401 Unauthorized access.
data object
error string
404 No Parquet cleanup has ever been requested on this cluster.
POST /api/v3/enterprise/upgrade/parquet_cleanup

Request Parquet cleanup after a storage engine upgrade

Requests removal of the Parquet-era data left behind by a completed Parquet-to-PachaTree storage engine upgrade. Any node in the cluster accepts the request. The compactor node executes it.

Requires the cluster to be fully on the upgraded (PachaTree) storage engine, with the Parquet-to-PachaTree upgrade already complete. Use dry_run to count and size the data a real cleanup would delete without deleting anything.

This endpoint is only available in InfluxDB 3 Enterprise.

Request body

Content-Type: application/json
dry_run boolean
When true, only count and size the Parquet-era data a real cleanup would delete. Delete nothing.
Example request body
{
  "dry_run": false
}
Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/api/v3/enterprise/upgrade/parquet_cleanup" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{"dry_run":false}'

Responses

202 Success. The cleanup started, is already running, or already completed.
state required string
The outcome of this cleanup request.
Allowed: started , already_running , already_completed
status required object
Point-in-time view of the durable Parquet cleanup state. Returned by GET /api/v3/enterprise/upgrade/parquet_cleanup and embedded in the POST response.
Example: {"bytes_deleted":4294967296,"bytes_matched":4294967296,"completed_at_ns":1735689900000000000,"files_deleted":812,"files_failed":0,"files_matched":812,"files_scanned":1024,"last_message":null,"mode":"delete","requested_at_ns":1735689600000000000,"requested_by":"node-1","started_at_ns":1735689601000000000,"status":"completed","updated_at_ns":1735689900000000000}
bytes_deleted required integer <int64>
Total size, in bytes, of the deleted files. Always 0 in dry_run mode.
bytes_matched required integer <int64>
Total size, in bytes, of the matched files.
completed_at_ns integer <int64>
When the cleanup finished, in nanoseconds since the Unix epoch.
files_deleted required integer <int64>
Number of files deleted so far. Always 0 in dry_run mode.
files_failed required integer <int64>
Number of files the cleanup failed to delete.
files_matched required integer <int64>
Number of files identified as Parquet-era data to delete.
files_scanned required integer <int64>
Number of files the cleanup has scanned so far.
last_message string
The most recent human-readable status message, if any.
mode required string
Whether this cleanup deletes data or only reports what it would delete.
Allowed: delete , dry_run
requested_at_ns integer <int64>
When the cleanup was requested, in nanoseconds since the Unix epoch.
requested_by string
The node that accepted the cleanup request, if recorded.
started_at_ns integer <int64>
When the cleanup started running, in nanoseconds since the Unix epoch.
status required string
The cleanup’s current status.
Allowed: requested , running , completed , failed
updated_at_ns integer <int64>
When this status was last updated, in nanoseconds since the Unix epoch.
401 Unauthorized access.
data object
error string
409 The cluster isn’t on the upgraded storage engine, no Parquet-to-PachaTree upgrade was ever recorded, the upgrade hasn’t completed, or a cleanup is already active in a different mode (dry run vs. delete).
POST /api/v3/enterprise/upgrade/retry_parquet_to_pacha_tree

Retry a failed Parquet-to-PachaTree upgrade

Resets a Parquet-to-PachaTree storage engine upgrade that latched to a failed state, so it resumes the next time a compactor node starts with --upgrade-pacha-tree.

Re-checks every previously failed upgrade source against the catalog and object store: sources that are still readable are requeued, sources whose table or database was dropped are recorded as skipped, and sources that can’t be read back are left unresolved for the next retry.

This endpoint is only available in InfluxDB 3 Enterprise.

Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/api/v3/enterprise/upgrade/retry_parquet_to_pacha_tree" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. Returns a summary of what the retry changed.
entries_already_converted required integer <int64>
Entries whose sequence already held converted data. Recorded as imported instead of skipped.
entries_already_skipped required integer <int64>
Terminal failures that were already recorded as skips.
entries_inspected required integer <int64>
Terminal failures the retry re-checked against the catalog and object store.
entries_requeued required integer <int64>
Entries returned to the queue because their source is still readable.
entries_skipped_source_missing required integer <int64>
Entries skipped because their source object no longer exists.
entries_skipped_table_dropped required integer <int64>
Entries skipped because their table was dropped.
entries_unresolved required integer <int64>
Entries left untouched because the object holding their sequence couldn’t be read back. Run this endpoint again to re-attempt them.
message required string
What to do next.
upgrade_status required string
The status the enterprise upgrade state was left in after the retry.
Example request body
{
  "entries_already_converted": 0,
  "entries_already_skipped": 0,
  "entries_inspected": 3,
  "entries_requeued": 2,
  "entries_skipped_source_missing": 1,
  "entries_skipped_table_dropped": 0,
  "entries_unresolved": 0,
  "message": "Migration state reset. Restart the compactor node with --upgrade-pacha-tree to resume the upgrade.",
  "upgrade_status": "upgrading"
}
401 Unauthorized access.
data object
error string
409 The upgrade isn’t in a state this request can act on (for example, it isn’t failed), or another request already reset it.
GET /api/v1/health

Health check (v1)

Checks the status of the service.

Returns OK if the service is running. This endpoint does not return version information. Use the /ping endpoint to retrieve version details.

Note: This endpoint requires authentication by default in InfluxDB 3 Enterprise.

Example request Ask AI about this
curl --request GET \
  "https://localhost:8181/api/v1/health" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Service is running. Returns OK.
401 Unauthorized. Authentication is required.
500 Service is unavailable.
GET /health

Health check

Checks the status of the service.

Returns OK if the service is running. This endpoint does not return version information. Use the /ping endpoint to retrieve version details.

Note: This endpoint requires authentication by default in InfluxDB 3 Enterprise.

Example request Ask AI about this
curl --request GET \
  "https://localhost:8181/health" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Service is running. Returns OK.
401 Unauthorized. Authentication is required.
500 Service is unavailable.
GET /metrics

Metrics

Retrieves Prometheus-compatible server metrics.
Example request Ask AI about this
curl --request GET \
  "https://localhost:8181/metrics" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success
GET /ping

Ping the server

Returns version information for the server.

Important: Use a GET request. HEAD requests return 404 Not Found.

The response includes version information in both headers and the JSON body:

  • Headers: x-influxdb-version and x-influxdb-build
  • Body: JSON object with version, revision, and process_id

Note: This endpoint requires authentication by default in InfluxDB 3 Enterprise.

Example request Ask AI about this
curl --request GET \
  "https://localhost:8181/ping" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains server information.
process_id string
A unique identifier for the server process.
Example: "b756d9e0-cecd-4f72-b6d0-19e2d4f8cbb7"
revision string
The git revision hash for the build.
Example: "83b589b883"
version string
The InfluxDB version number.
Example: "3.8.0"
401 Unauthorized. Authentication is required.
404 Not Found. Returned for HEAD requests. Use a GET request to retrieve version information.
POST /ping

Ping the server

Returns version information for the server. Accepts POST in addition to GET.
Example request Ask AI about this
curl --request POST \
  "https://localhost:8181/ping" \
  --header "Authorization: Bearer INFLUX_TOKEN"

Responses

200 Success. The response body contains server information.
process_id string
A unique identifier for the server process.
Example: "b756d9e0-cecd-4f72-b6d0-19e2d4f8cbb7"
revision string
The git revision hash for the build.
Example: "83b589b883"
version string
The InfluxDB version number.
Example: "3.8.0"
401 Unauthorized. Authentication is required.
404 Not Found. Returned for HEAD requests. Use a GET request to retrieve version information.

Was this page helpful?

Thank you for your feedback!