Prometheus Integration API
Base path: /api/v1/prometheus
Implementation reference: internal/handlers/prometheus.go, models in internal/models/prometheus.go.
Endpoints
| Method | Path | Description | Auth Required |
|---|---|---|---|
| POST | /prometheus/calculate-slo | Calculate SLO metrics for a specific SLO | Yes |
| GET | /prometheus/real-time-metrics | Get real-time metrics for all active SLOs | Yes |
| POST | /prometheus/queries | Create a Prometheus query configuration | Yes |
| GET | /prometheus/queries | List Prometheus queries for an SLO | Yes |
| GET | /prometheus/queries/:id/executions | Get query execution history | Yes |
| POST | /prometheus/query | Execute an ad-hoc Prometheus query | Yes |
| GET | /prometheus/health | Check Prometheus data source health | Yes |
POST /prometheus/calculate-slo
Calculates SLO compliance metrics by querying Prometheus over the specified time window. The calculation service (internal/prometheus/SLOCalculationService) executes the stored metric query and returns the current value, error budget usage, and status.
Request:
{
"slo_id": 1,
"time_window": "24h",
"include_details": true
}| Field | Type | Description |
|---|---|---|
slo_id | int | SLO ID to calculate metrics for |
time_window | string | One of: 5m, 15m, 30m, 1h, 6h, 24h, 7d, 30d |
include_details | bool | Include query execution details in response |
extend_time | string (ISO 8601) | Optional end time (defaults to now) |
Response (200 OK):
{
"slo_id": 1,
"time_window": "24h",
"start_time": "2026-06-10T10:00:00Z",
"end_time": "2026-06-11T10:00:00Z",
"current_value": 99.92,
"target_value": 99.9,
"error_budget_used": 20.0,
"status": "healthy",
"calculated_at": "2026-06-11T10:00:00Z",
"query_executions": [
{
"id": 42,
"query_id": 1,
"slo_id": 1,
"execution_time": "2026-06-11T10:00:00Z",
"execution_duration_ms": 150,
"status": "success",
"result_samples": 1440
}
]
}SLO status values: healthy, warning, critical, unknown.
GET /prometheus/real-time-metrics
Returns current SLO metrics for all active SLOs in the user's organization. Metrics are computed from the last known Prometheus data.
Response (200 OK):
{
"metrics": [
{
"slo_id": 1,
"current_status": "healthy",
"current_value": 99.95,
"error_budget_percent": 50.0,
"last_updated": "2026-06-11T10:00:00Z",
"trends": {
"24h_change": -0.02,
"7d_change": 0.05
}
}
],
"total": 1
}POST /prometheus/queries
Creates a Prometheus query configuration associated with an SLO. The query is periodically evaluated by the calculation service.
Request:
{
"slo_id": 1,
"query_name": "Error Rate Query",
"prometheus_query": "rate(http_requests_total{job=\"api\",status=~\"5..\"}[5m])",
"query_type": "availability",
"metric_labels": ["job", "status"],
"evaluation_interval_seconds": 300
}Response (201 Created):
{
"id": 1,
"slo_id": 1,
"query_name": "Error Rate Query",
"prometheus_query": "rate(http_requests_total{job=\"api\",status=~\"5..\"}[5m])",
"query_type": "availability",
"query_hash": "aBcDeFgHiJkLmNoPqRsTuVwXyZ...",
"metric_labels": ["job", "status"],
"evaluation_interval_seconds": 300,
"is_active": true,
"created_at": "2026-06-11T10:00:00Z",
"updated_at": "2026-06-11T10:00:00Z"
}Supported query_type values: availability, latency, throughput, error_rate, custom.
GET /prometheus/queries
Lists all Prometheus query configurations for a specific SLO. The SLO ID is extracted from the URL path as /api/v1/prometheus/queries — the actual route extracts the SLO ID from the path position (e.g., /api/v1/prometheus/queries).
Response (200 OK):
{
"queries": [
{
"id": 1,
"slo_id": 1,
"query_name": "Error Rate Query",
"prometheus_query": "rate(http_requests_total{job=\"api\",status=~\"5..\"}[5m])",
"query_type": "availability",
"is_active": true,
"created_at": "2026-06-11T10:00:00Z",
"updated_at": "2026-06-11T10:00:00Z"
}
],
"total": 1
}GET /prometheus/queries/:id/executions
Returns the execution history for a specific Prometheus query.
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | int | 100 | Maximum number of execution records |
Response (200 OK):
{
"executions": [
{
"id": 42,
"query_id": 1,
"slo_id": 1,
"execution_time": "2026-06-11T10:00:00Z",
"execution_duration_ms": 150,
"status": "success",
"result_samples": 1440,
"metadata": {
"time_range": "24h",
"prometheus_source": "primary"
},
"created_at": "2026-06-11T10:00:00Z"
}
],
"total": 1
}POST /prometheus/query
Executes an ad-hoc Prometheus query against the configured data source.
Request:
{
"query": "rate(http_requests_total{job=\"api\"}[5m])",
"time_range": "1h",
"step": "15s"
}| Field | Type | Description |
|---|---|---|
query | string | PromQL query string |
time_range | string | One of: 5m, 15m, 30m, 1h, 6h, 24h, 7d, 30d |
step | string | Query resolution step (e.g. 15s, 1m, 5m) |
extend_time | string (ISO 8601) | Optional end time |
Response (200 OK):
{
"query_result": {
"result_type": "vector",
"result": [
{
"metric": { "job": "api", "status": "200" },
"value": [1718100000, "0.05"]
}
]
},
"status": "success",
"metadata": {
"time_range": "1h",
"start_time": "2026-06-11T09:00:00Z",
"end_time": "2026-06-11T10:00:00Z"
},
"queried_at": "2026-06-11T10:00:00Z"
}GET /prometheus/health
Checks the health of all active Prometheus data sources. Each data source is tested by executing a simple up query.
Response (200 OK):
{
"data_sources": [
{
"id": 1,
"organization_id": 1,
"api_url": "http://prometheus:9090",
"is_active": true,
"status": "healthy",
"last_check": "2026-06-11T10:00:00Z"
}
],
"total": 1,
"checked_by": 1,
"timestamp": "2026-06-11T10:00:00Z"
}If all data sources are healthy, status is 200 OK. If any data source is unreachable, status is 503 Service Unavailable and the individual datasource includes an error field.
Error Codes
| HTTP Status | Scenario |
|---|---|
400 | Invalid request body, invalid time range, missing query |
404 | SLO not found for the given slo_id |
500 | Prometheus query execution failure |
503 | Prometheus data source is unreachable |