HTTP API
import { Aside } from ‘@astrojs/starlight/components’;
The default HTTP listener binds to 0.0.0.0:3100. Product-neutral routes and OTLP ingestion are always present; compatibility aliases are mounted only when PULSUS_COMPAT_ENDPOINTS=true.
Common request headers
Section titled “Common request headers”| Header | Purpose |
|---|---|
Authorization |
Basic authentication when configured |
X-Pulsus-Database |
Route a request to an allowed database/tenant |
X-Pulsus-Async |
Override synchronous or asynchronous ingest behavior |
X-Pulsus-Explain |
Include query planning and generated SQL details |
Ingestion
Section titled “Ingestion”| Method and path | Signal / format |
|---|---|
POST /v1/logs |
OTLP logs, protobuf |
POST /v1/metrics |
OTLP metrics, protobuf |
POST /v1/traces |
OTLP traces, protobuf |
POST /v1development/profiles |
Experimental OTLP profiles, protobuf |
POST /api/v1/write |
Prometheus remote write, snappy protobuf |
POST /api/profiles/v1/ingest |
pprof profile ingest |
Successful OTLP writes use the OTLP response contract. A full ingest queue returns 429; an oversized push returns 413.
| Method and path | Purpose |
|---|---|
| `GET | POST /api/logs/v1/query_range` |
| `GET | POST /api/logs/v1/query` |
| `GET | POST /api/logs/v1/labels` |
| `GET | POST /api/logs/v1/label/{name}/values` |
| `GET | POST /api/logs/v1/series` |
GET /api/logs/v1/tail |
WebSocket live tail |
| `GET | POST /api/logs/v1/stats` |
Metrics
Section titled “Metrics”PulsusDB implements the Prometheus HTTP API:
| Method and path | Purpose |
|---|---|
| `GET | POST /api/v1/query` |
| `GET | POST /api/v1/query_range` |
| `GET | POST /api/v1/series` |
| `GET | POST /api/v1/labels` |
GET /api/v1/label/{name}/values |
Label values |
GET /api/v1/metadata |
Metric metadata |
Traces
Section titled “Traces”| Method and path | Purpose |
|---|---|
GET /api/traces/v1/trace/{trace_id} |
Fetch one trace |
GET /api/traces/v1/search |
Search with TraceQL and filters |
GET /api/traces/v1/search/tags |
Discover tag names |
GET /api/traces/v1/search/tag/{name}/values |
Discover tag values |
GET /api/traces/v1/service_graph |
PulsusDB-native service graph data |
Operations
Section titled “Operations”| Method and path | Purpose |
|---|---|
GET /ready |
Readiness, including ClickHouse and reader warm-up |
GET /metrics |
Prometheus metrics about PulsusDB |
GET /config |
Effective redacted configuration |
GET /buildinfo |
Build and version metadata |
GET /admin/ |
Admin UI with its own Basic auth pair |
Compatibility endpoints
Section titled “Compatibility endpoints”When enabled, aliases include Loki-compatible query and push paths plus selected trace and profile datasource routes. Compatibility endpoints are an integration bridge, not the preferred API for new clients.
Error model
Section titled “Error model”Query APIs return a structured error with an HTTP status appropriate to malformed syntax, invalid parameters, timeouts, or resource limits. Ingest APIs preserve their protocol-specific error format where interoperability requires it.