HTTP API Endpoint List

GreptimeDB provides two HTTP servers:

Server	Default address	Purpose
Main HTTP server	127.0.0.1:4000	Internal / operational use. Serves all paths, including admin endpoints such as /health, /metrics, /config, and /debug/*, as well as all /v1 and /dashboard paths. Keep this port private and accessible only by trusted operators.
Public HTTP API server	127.0.0.1:4006	User-facing API traffic. Serves only /v1 APIs and /dashboard, excluding the admin endpoints. Disabled by default; enable it with http.enable_api_server = true in your configuration file.

Keep the main HTTP server private. To expose GreptimeDB APIs to end users, enable the public API server and expose only that port.

warning

The public API server reduces the exposed route surface, but route filtering does not provide authentication or transport security. With no user_provider configured, GreptimeDB accepts requests without authentication. Before allowing external access, configure authentication, TLS, and network access controls, either directly or through a reverse proxy.

[http]
# Main HTTP server — keep this internal
addr = "127.0.0.1:4000"

# Enable the public API server and bind it for external access
enable_api_server = true
api_server_addr = "0.0.0.0:4006"

See the configuration documentation for all [http] options.

The following sections describe the commonly used HTTP paths:

Admin APIs

Unversioned endpoints outside /v1, used for health checks, status, metrics, and other administrative operations.

note

Admin API endpoints are available only on the main HTTP server (default port 4000). They are not exposed by the dedicated public API server even when http.enable_api_server is enabled.

Health Check

• Path: /health
• Methods: GET, POST
• Description: Provides a health check endpoint to verify that the server is running.
• Usage: Access this endpoint to check the health status of the server.

Please refer to the check GreptimeDB health documentation for an example.

Status

• Path: /status
• Methods: GET
• Description: Retrieves the current status of the server.
• Usage: Use this endpoint to obtain server status information.

Please refer to the Check GreptimeDB status documentation for an example.

Metrics

• Path: /metrics
• Methods: GET
• Description: Exposes Prometheus metrics for monitoring purposes.
• Usage: Prometheus can scrape this endpoint to collect metrics data.

Example:

curl -X GET http://127.0.0.1:4000/metrics

Output:

# HELP greptime_app_version app version
# TYPE greptime_app_version gauge
greptime_app_version{app="greptime-edge",short_version="main-b4bd34c5",version="0.12.0"} 1
# HELP greptime_catalog_catalog_count catalog catalog count
# TYPE greptime_catalog_catalog_count gauge
greptime_catalog_catalog_count 1
# HELP greptime_catalog_schema_count catalog schema count
# TYPE greptime_catalog_schema_count gauge
greptime_catalog_schema_count 3
# HELP greptime_flow_run_interval_ms flow run interval in ms
# TYPE greptime_flow_run_interval_ms gauge
greptime_flow_run_interval_ms 1000
# HELP greptime_meta_create_catalog meta create catalog
# TYPE greptime_meta_create_catalog histogram
greptime_meta_create_catalog_bucket{le="0.005"} 1
greptime_meta_create_catalog_bucket{le="0.01"} 1
greptime_meta_create_catalog_bucket{le="0.025"} 1
greptime_meta_create_catalog_bucket{le="0.05"} 1
greptime_meta_create_catalog_bucket{le="0.1"} 1
...

Configuration

• Path: /config
• Methods: GET
• Description: Retrieves the server's configuration options.
• Usage: Access this endpoint to get configuration details.

For example:

curl http://localhost:4000/config

The output contains the configuration information of the GreptimeDB server.

enable_telemetry = true
user_provider = "static_user_provider:file:user"
init_regions_in_background = false
init_regions_parallelism = 16

[http]
addr = "127.0.0.1:4000"
timeout = "30s"
body_limit = "64MiB"
is_strict_mode = false

# ...

Dashboard

• Paths: /dashboard
• Methods: GET, POST
• Description: Provides access to the server's dashboard interface.
• Usage: Access these endpoints to interact with the web-based dashboard.

The dashboard is packaged with GreptimeDB when the corresponding build feature is enabled. Its source code is in the GreptimeDB Dashboard repository.

Log Level

• Path: /debug/log_level
• Methods: POST
• Description: Adjusts the server's log level dynamically.
• Usage: Send a log level change request to this endpoint.

For more information, refer to the how-to documentation.

Enable/Disable Trace

• Path: /debug/enable_trace
• Methods: POST
• Description: Dynamically enables or disables distributed tracing at runtime.
• Usage: Send true to enable tracing or false to disable tracing.

Example to enable tracing:

curl --data "true" http://127.0.0.1:4000/debug/enable_trace
# Output: trace enabled

Example to disable tracing:

curl --data "false" http://127.0.0.1:4000/debug/enable_trace
# Output: trace disabled

For more information on tracing configuration, refer to the tracing documentation.

Profiling Tools

• Base Path: /debug/prof/
• Description: Runtime profiling for CPU or memory usage on the database node.

CPU profiling:

Path	Method	Description
/debug/prof/cpu	POST	Collects a CPU profile. Query parameters include seconds, frequency, and output. Supported output formats are proto, text, and flamegraph.

Example:

curl -X POST -s 'http://127.0.0.1:4000/debug/prof/cpu?seconds=10&output=flamegraph' > greptime-cpu.svg

Memory profiling:

Path	Method	Description
/debug/prof/mem	POST	Dumps memory profiling data. Query parameter output supports text, proto, and flamegraph.
/debug/prof/mem/status	GET	Checks whether heap profiling is active.
/debug/prof/mem/activate	POST	Activates heap profiling.
/debug/prof/mem/deactivate	POST	Deactivates heap profiling.
/debug/prof/mem/gdump	GET	Checks whether jemalloc gdump is active.
/debug/prof/mem/gdump	POST	Activates or deactivates jemalloc gdump. Use form field activate=true or activate=false.
/debug/prof/mem/symbol	POST	Uploads a jemalloc heap dump file and returns a symbolicated flamegraph.

Examples:

curl -X POST -s 'http://127.0.0.1:4000/debug/prof/mem?output=flamegraph' > greptime-mem.svg
curl -X GET 'http://127.0.0.1:4000/debug/prof/mem/status'
curl -X POST 'http://127.0.0.1:4000/debug/prof/mem/gdump' -d 'activate=true'

For operational guidance, see Collect profiling data. For advanced usage, refer to Profiling CPU and Profiling Memory.

Query Endpoints

These endpoints execute SQL, PromQL, or structured log queries.

SQL API

• Path: /v1/sql
• Methods: GET, POST
• Description: Executes SQL queries against the server.
• Usage: Send SQL queries in the request body.

For more information on the SQL API, refer to the HTTP API documentation in the user guide.

Format SQL API

• Path: /v1/sql/format
• Methods: GET, POST
• Description: Rewrites an SQL statement into the canonical form of GreptimeDB's SQL dialect. Available since v0.17.
• Usage: Pass the SQL in the sql query parameter, or in the form body of a POST request, which must set Content-Type: application/x-www-form-urlencoded. Returns a JSON object {"formatted": "..."} holding the normalized SQL string.

For more information on the Format SQL API, refer to the HTTP API documentation in the user guide.

Parse SQL API

• Path: /v1/sql/parse
• Methods: GET, POST
• Description: Parses SQL and returns the GreptimeDB statement representation without executing it.
• Usage: Pass SQL in the sql query parameter or in an application/x-www-form-urlencoded form body.

PromQL API

• Path: /v1/promql
• Methods: GET, POST
• Description: Executes PromQL queries for Prometheus-compatible metrics, and returns data in GreptimeDB's JSON format.
• Usage: Send PromQL queries in the request body.

For more information on the PromQL API, refer to the PromQL documentation.

Streaming query analysis

POST /v1/sql/analyze/stream returns Server-Sent Events (SSE) with content type text/event-stream for query metrics during execution. The endpoint is available by default and requires no configuration switch.

Parameters can be passed in the URL query string or an application/x-www-form-urlencoded body. URL parameters take precedence over body parameters with the same name.

Parameter	Requirement	Description
sql	Required	One EXPLAIN ANALYZE VERBOSE or TQL ANALYZE VERBOSE statement. Omit the format or use FORMAT JSON; other formats are unsupported.
db	Optional	Database. Defaults to public.
snapshot_interval_ms	Optional	Metrics snapshot interval in milliseconds. Defaults to 5000 and is clamped to 1000–60000. For snapshot payloads of at least 1 MiB, the interval is at least 10 seconds; at least 10 MiB raises it to at least 30 seconds.

Example request:

curl -N -X POST 'http://127.0.0.1:4000/v1/sql/analyze/stream' \
  --data-urlencode 'db=public' \
  --data-urlencode 'sql=EXPLAIN ANALYZE VERBOSE SELECT count(*) FROM information_schema.tables' \
  --data-urlencode 'snapshot_interval_ms=1000'

Each event has an event: line and a data: line containing JSON, separated from the next event by a blank line. The server sends a keep-alive comment every 15 seconds while the connection remains open.

Field	Type	Description
seq	Integer	Monotonically increasing event sequence number.
state	String	metrics, final, canceled, or error.
partial	Boolean	true for metrics events; false for terminal events.
elapsed_ms	Integer	Milliseconds since the request started.
metrics	Array	A stage / node / plan snapshot, when available. Periodic events contain compact execution topology and runtime metrics; terminal events include verbose plan details.
output	Object	Final query result, present only in final events.
reason	String	Failure or cancellation reason, present only in error and canceled events.
code	Integer	GreptimeDB status code, present only in error and canceled events; cancellation uses 1005 (Cancelled).

Snapshots contain all collected metrics, not deltas; values can change during collection. Snapshots are throttled but never truncated.

Event	Behavior
metrics	A complete metrics snapshot. Slow clients can skip intermediate snapshots, so seq is not necessarily consecutive.
final	Query completed.
error	Query failed.
canceled	Query canceled.

final, error, and canceled are terminal events. A short query can return final without a metrics event. Validation failures before streaming return a regular JSON error response. On client disconnect, the server makes a best-effort attempt to cancel the query; the disconnected client receives no canceled event. Browser EventSource does not support this POST endpoint. Use an HTTP client that supports streaming responses. Events are delivered only to the current connection. The stream does not support resume, reconnect, or detached execution.

Protocol Endpoints

These endpoints implement selected APIs from InfluxDB, Prometheus, OpenTelemetry, Loki, Splunk HEC, and OpenTSDB.

InfluxDB Compatibility

• Paths:
  • /v1/influxdb/write
  • /v1/influxdb/api/v2/write
  • /v1/influxdb/ping
  • /v1/influxdb/health
• Methods:
  • POST for write endpoints.
  • GET for ping and health endpoints.
• Description: Provides endpoints compatible with InfluxDB for data ingestion and health checks.
• Usage:
  • Ingest data using InfluxDB line protocol.
  • Use ping and health endpoints to check server status.

The detailed documentation for InfluxDB protocol can be found at here.

Prometheus Remote Write/Read

• Paths:
  • /v1/prometheus/write
  • /v1/prometheus/read
• Methods: POST
• Description: Supports Prometheus remote write and read APIs.
• Usage:
  • Send metric data using Prometheus remote write protocol.
  • Read metric data using Prometheus remote read protocol.

Prometheus HTTP API

• Base Path: /v1/prometheus/api/v1
• Endpoints:
  • /format_query
  • /status/buildinfo
  • /query
  • /query_range
  • /labels
  • /metadata
  • /series
  • /parse_query
  • /label/{label_name}/values
• Methods: GET, POST
• Description: Provides Prometheus HTTP API endpoints for querying and retrieving metric data.
• Usage: Use these endpoints to interact with metrics using standard Prometheus HTTP API.

Refer to the original Prometheus documentation for more information on the Prometheus HTTP API.

OpenTelemetry Protocol (OTLP)

• Paths:
  • /v1/otlp/v1/metrics
  • /v1/otlp/v1/traces
  • /v1/otlp/v1/logs
• Methods: POST
• Description: Supports OpenTelemetry protocol for ingesting metrics, traces, and logs.
• Usage: Send OpenTelemetry formatted data to these endpoints.

Loki Compatibility

• Path: /v1/loki/api/v1/push
• Methods: POST
• Description: Compatible with Loki's API for log ingestion.
• Usage: Send log data in Loki's format to this endpoint.

Splunk HEC Compatibility

• Path: /v1/splunk/services/collector/event, /v1/splunk/services/collector/raw, /v1/splunk/services/collector/health
• Methods: POST for the ingestion endpoints, GET for the health endpoint
• Description: Compatible with the Splunk HTTP Event Collector (HEC) protocol for log ingestion.
• Usage: Send JSON events to /event or plain text to /raw. See Ingest Data with Splunk.

OpenTSDB Protocol

• Path: /v1/opentsdb/api/put
• Methods: POST
• Description: Supports data ingestion using the OpenTSDB protocol.
• Usage: Ingest time series data using OpenTSDB's JSON format.

Log and Pipeline Endpoints

Path	Methods	Description
/v1/ingest	POST	Ingests logs through a Pipeline.
/v1/logs	GET, POST	Executes a structured log query. The request uses a JSON body; POST is the usual method.
/v1/pipelines/{pipeline_name}	GET	Returns a Pipeline definition.
/v1/pipelines/{pipeline_name}	POST	Creates or replaces a Pipeline.
/v1/pipelines/{pipeline_name}	DELETE	Deletes a Pipeline.
/v1/pipelines/{pipeline_name}/ddl	GET	Returns the table DDL inferred from a Pipeline.
/v1/pipelines/_dryrun	POST	Runs a Pipeline against sample input without ingesting the result.

See Log overview, Log query, and Pipeline configuration.