victoriametrics vmanomaly API
Operate a running vmanomaly v1.30+ instance through bounded, explicit API calls. Prefer live schemas and server responses over static assumptions.
Environment and authentication
# Include any configured path prefix in the base URL.
export VM_ANOMALY_URL="https://vmanomaly.example.com"
# Use /dev/null for unauthenticated local instances. For authenticated instances, point this to
# a mode-0600 curl config containing: header = "Authorization: Bearer <token>"
export VM_CURL_CONFIG="${VM_CURL_CONFIG:-/dev/null}"
Keep credentials out of process arguments and use the same config for every request:
curl -q --config "$VM_CURL_CONFIG" -s \
"$VM_ANOMALY_URL/health" | jq .
Never print or create the credential file. Ask for VM_ANOMALY_URL when it is unset.
Start with a runtime preflight
Run these checks before configuration, review, autotune, or migration work:
curl -q --config "$VM_CURL_CONFIG" -s \
"$VM_ANOMALY_URL/health" | jq .
curl -q --config "$VM_CURL_CONFIG" -s \
"$VM_ANOMALY_URL/api/v1/server/buildinfo" | jq .
curl -q --config "$VM_CURL_CONFIG" -s \
"$VM_ANOMALY_URL/api/v1/compatibility" | jq .
Interpret compatibility conservatively:
global_check.has_state=false: no persisted state needs migration.global_check.is_compatible=true: the covered vmanomaly-managed state can be reused.global_check.drop_everything=true: report that all persisted state must be dropped; do not perform the drop automatically.component_assessment.models_to_purgeorshould_purge_reader_data: report the scoped cleanup.- Use
?version_to=X.Y.Zto assess the stored state against a planned target release.
Compatibility covers vmanomaly-managed state, supported readers, and built-in models, not custom model code, dependencies, or state; before upgrading to v1.30.3+, custom many-to-one models relying on is_multivariate = True must declare topology = ModelTopology.MANY_TO_ONE.
Only GET compatibility is implemented. Do not invent a POST endpoint for arbitrary provided configs. For configuration syntax, use /api/v1/config/validate instead.
Discover capabilities before using them
curl -q --config "$VM_CURL_CONFIG" -s \
"$VM_ANOMALY_URL/api/v1/models" | jq .
curl -q --config "$VM_CURL_CONFIG" -sG \
--data-urlencode 'model_class=temporal_envelope' \
"$VM_ANOMALY_URL/api/v1/model/schema" | jq .
Treat /api/v1/models and /api/v1/model/schema as authoritative. Do not carry parameters between model classes unless the target schema exposes them.
Validate before running
Validate one model:
curl -q --config "$VM_CURL_CONFIG" -s \
-X POST -H 'Content-Type: application/json' \
-d '{"class":"temporal_envelope","seasonalities":["hod_smooth","dow_smooth"]}' \
"$VM_ANOMALY_URL/api/v1/model/validate" | jq .
Validate a complete configuration:
curl -q --config "$VM_CURL_CONFIG" -s \
-X POST -H 'Content-Type: application/yaml' \
--data-binary @config.yaml \
"$VM_ANOMALY_URL/api/v1/config/validate" | jq .
Validation does not apply or reload a configuration.
Inspect the running server
# Configured query aliases and expressions.
curl -q --config "$VM_CURL_CONFIG" -s \
"$VM_ANOMALY_URL/api/v1/server/queries" | jq .
# Configured datasource context. Keep only documented fields and redact URL user information.
curl -q --config "$VM_CURL_CONFIG" -s \
"$VM_ANOMALY_URL/api/v1/server/datasource" | jq '
with_entries(select(.key | IN("server_datasource_url", "ui_datasource_url", "ui_datasource_type")))
| with_entries(
if (.value | type) == "string" and (.key | endswith("_url"))
then .value |= sub("://[^/@]+@"; "://<redacted>@")
else .
end
)'
# Prometheus-format self-monitoring metrics.
curl -q --config "$VM_CURL_CONFIG" -s \
"$VM_ANOMALY_URL/metrics?name[]=vmanomaly_scheduler_alive&name[]=vmanomaly_scheduler_restarts_total&name[]=vmanomaly_model_run_errors&name[]=vmanomaly_model_runs_skipped"
Treat /health as a point-in-time preflight, not production monitoring. For a running deployment, recommend scraping or pushing the documented self-monitoring metrics, installing the Grafana dashboard, and reviewing the supplied alerting rules. Prioritize service availability, scheduler liveness/restarts, reload failures, model errors/skips, I/O error rates, and resource pressure. Do not deploy rules or dashboards without user approval.
When installed, use victoriametrics-query to verify that self-monitoring series are ingested and the expected rules are loaded; use alertmanager-query to inspect active, silenced, or inhibited vmanomaly alerts.
Profile a query before choosing a model
An exact non-empty query is required. If the user supplied one, reuse it. Otherwise resolve a configured query alias or ask the user; never invent a production query from a metric description.
QUERY='sum(rate(http_requests_total{job="api"}[5m])) by (service)'
TIMEZONE='America/New_York'
curl -q --config "$VM_CURL_CONFIG" -sG \
--data-urlencode "query=$QUERY" \
--data-urlencode 'start=<unix-seconds>' \
--data-urlencode 'end=<unix-seconds>' \
--data-urlencode 'step=5m' \
--data-urlencode "timezone=$TIMEZONE" \
--data-urlencode 'limit=100' \
"$VM_ANOMALY_URL/api/v1/timeseries/characteristics" | jq .
Use the same step for profiling, autotune, and the final task/config. Treat a limited response as a sample, not an exact population summary. If a limited read returns a split-chunk 422, use a shorter interval or coarser step.
Run shared autotune
Choose tuned_class_name first from the profile, business intent, /api/v1/models, and schema. Shared v1.30 autotune does not choose the model class.
jq -n --arg query "$QUERY" --arg timezone "$TIMEZONE" '{
query:$query,
"tuned_class_name":"temporal_envelope",
"anomaly_percentage":0.02,
"start":1710000000,
"end":1711209600,
"step":"5m",
timezone:$timezone,
"limit":100,
"use_profile_hints":true,
"optimization_params":{"n_trials":64,"timeout":30,"exact":true,"optimize_complexity":true},
"frozen_params":{"detection_direction":"above_expected"}
}' | curl -q --config "$VM_CURL_CONFIG" -s \
-X POST -H 'Content-Type: application/json' --data-binary @- \
"$VM_ANOMALY_URL/api/v1/autotune/tasks" | jq .
Tell the user the trial/time budget before creating the task. Poll one task sequentially:
curl -q --config "$VM_CURL_CONFIG" -s \
"$VM_ANOMALY_URL/api/v1/autotune/tasks/<task_id>" | jq .
Treat done, error, and canceled as terminal. On done, apply result_data.data.modelConfig directly, validate it, and test it. Do not replace this concrete one-time recommendation with class: auto; the deployable auto wrapper has a different lifecycle. Business policies in this result remain model-spec fields for task/UI compatibility; move them to the attached query only when constructing a v1.30.2+ deployment configuration. Use DELETE only when the user asks to cancel:
curl -q --config "$VM_CURL_CONFIG" -s \
-X DELETE "$VM_ANOMALY_URL/api/v1/autotune/tasks/<task_id>" | jq .
Run bounded detection tasks
Check capacity first:
curl -q --config "$VM_CURL_CONFIG" -s \
"$VM_ANOMALY_URL/api/v1/anomaly_detection/limits" | jq .
Create a task only after validating model_spec. The v1.30.3 task contract requires an explicit datasource_url; reuse the configured datasource URL when appropriate:
DATASOURCE_URL='<configured-or-explicit-datasource-url>'
jq -n --arg query "$QUERY" --arg datasource_url "$DATASOURCE_URL" '{
query:$query,
datasource_url:$datasource_url,
"step":"5m",
"fit_window":"30d",
"fit_every":"1000d",
"start_infer_s":1710000000,
"end_infer_s":1710086400,
"exact":true,
"model_spec":{"class":"temporal_envelope","seasonalities":["hod_smooth","dow_smooth"]}
}' | curl -q --config "$VM_CURL_CONFIG" -s \
-X POST -H 'Content-Type: application/json' --data-binary @- \
"$VM_ANOMALY_URL/api/v1/anomaly_detection/tasks" | jq .
Use exact:true for causal online-model evaluation. Poll sequentially and never create duplicate tasks merely because a task is still running.
Generate deployment artifacts
Use /api/vmanomaly/config.yaml for an example configuration and /api/vmanomaly/example-alert-rule.yaml for a VMAlert rule. Pass values with --data-urlencode. The config endpoint preserves compatibility-oriented model-level business fields. For v1.30.2+ deployment YAML, move data_range, detection_direction, min_dev_from_expected, and min_rel_dev_from_expected to reader.queries.<alias>, consider reader.workers: 0 for bounded datasource concurrency, and validate the resulting complete configuration before presenting it.
Optional companion skills
- Use
victoriametrics-querywhen available to discover metric names, labels, cardinality, or existing alert/rule queries before constructing PromQL/MetricsQL. - Use
victorialogs-querywhen the datasource is VictoriaLogs and LogsQL discovery is needed. - Use
alertmanager-queryto check active alerts or avoid duplicating existing alerting intent.
These are optional enhancements. Continue through vmanomaly server/proxy endpoints when they are not installed.
Reference
Read references/api-reference.md for endpoint parameters, response fields, error handling, and v1.30 task semantics.