Skip to main content
Version: Nightly

HTTP API Endpoint List

Here is the full list for the various HTTP paths and their usage in GreptimeDB:

Admin APIs

Endpoints that is not versioned (under /v1). For admin usage like health check, status, metrics, etc.

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

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

This dashboard is packaged with the GreptimeDB server and provides a user-friendly interface for interacting with the server. It requires corresponding compile flags to be enabled when building GreptimeDB. The original source code for the dashboard can be found at https://github.com/GreptimeTeam/dashboard

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.

Profiling Tools

  • Base Path: /debug/prof/
  • Endpoints:
    • cpu
    • mem
  • Methods: POST for profiling the database node.
  • Description: Runtime profiling for CPU or Memory usage.
  • Usage:

Query Endpoints

Various query APIs for sending query to GreptimeDB.

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.

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.

Protocol Endpoints

Endpoints for various protocols that are compatible with GreptimeDB. Like InfluxDB, Prometheus, OpenTelemetry, etc.

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
    • /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.

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 Ingestion Endpoints

  • Paths:
    • /v1/events/logs
    • /v1/events/pipelines/{pipeline_name}
    • /v1/events/pipelines/dryrun
  • Methods:
    • POST for ingesting logs and adding pipelines.
    • DELETE for deleting pipelines.
  • Description: Provides endpoints for log ingestion and pipeline management.
  • Usage:
    • Ingest logs via the /logs endpoint.
    • Manage log pipelines using the /pipelines endpoints.

For more information on log ingestion and pipeline management, refer to the log overview.