VictoriaMetrics/docs/url-examples.md

sort
21

VictoriaMetrics API examples

/api/v1/admin/tsdb/delete_series

Deletes time series from VictoriaMetrics

Single:

curl -v 'http://<victoriametrics-addr>:8428/api/v1/admin/tsdb/delete_series?match[]=vm_http_request_errors_total'

The expected output should return HTTP Status 204 and will look like:

*   Trying 127.0.0.1:8428...
* Connected to 127.0.0.1 (127.0.0.1) port 8428 (#0)
> GET /api/v1/admin/tsdb/delete_series?match[]=vm_http_request_errors_total HTTP/1.1
> Host: 127.0.0.1:8428
> User-Agent: curl/7.81.0
> Accept: */*
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 204 No Content
< X-Server-Hostname: eba075fb0e1a
< Date: Tue, 21 Jun 2022 07:33:35 GMT
< 
* Connection #0 to host 127.0.0.1 left intact

Cluster:

curl -v'http://<vmselect>:8481/delete/0/prometheus/api/v1/admin/tsdb/delete_series?match[]=vm_http_request_errors_total'

The expected output should return HTTP Status 204 and will look like:

*   Trying 127.0.0.1:8481...
* Connected to 127.0.0.1 (127.0.0.1) port 8481 (#0)
> GET /delete/0/prometheus/api/v1/admin/tsdb/delete_series?match[]=vm_http_request_errors_total HTTP/1.1
> Host: 127.0.0.1:8481
> User-Agent: curl/7.81.0
> Accept: */*
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 204 No Content
< X-Server-Hostname: 101ed7a45c94
< Date: Tue, 21 Jun 2022 07:21:36 GMT
< 
* Connection #0 to host 127.0.0.1 left intact

Additional information:

• How to delete time series

/api/v1/export/csv

Exports CSV data from VictoriaMetrics

Single:

curl 'http://<victoriametrics-addr>:8428/api/v1/export/csv?format=__name__,__value__,__timestamp__:unix_s&match=vm_http_request_errors_total' > filename.txt

Cluster:

curl -G 'http://<vmselect>:8481/select/0/prometheus/api/v1/export/csv?format=__name__,__value__,__timestamp__:unix_s&match=vm_http_request_errors_total' > filename.txt

Additional information:

• How to export time series
• URL Format

/api/v1/export/native

Exports data from VictoriaMetrics in native format

Single:

curl -G 'http://<victoriametrics-addr>:8428/api/v1/export/native?match[]=vm_http_request_errors_total' > filename.txt

Cluster:

curl -G 'http://<vmselect>:8481/select/0/prometheus/api/v1/export/native?match=vm_http_request_errors_total' > filename.txt

More information:

• How to export data in native format

/api/v1/import

Imports custom data as well as data obtained via /api/v1/export

Single:

curl --data-binary "@import.txt" -X POST 'http://destination-victoriametrics:8428/api/v1/import'

Cluster:

curl --data-binary "@import.txt" -X POST 'http://<vminsert>:8480/insert/0/prometheus/api/v1/import'

curl -d 'metric_name{foo="bar"} 123' -X POST 'http://<vminsert>:8480/insert/0/prometheus/api/v1/import/prometheus'

Additional information:

• How to import time series data

/api/v1/import/csv

Imports CSV data to VictoriaMetrics

Single:

curl --data-binary "@import.txt" -X POST 'http://localhost:8428/api/v1/import/prometheus'
curl -d "GOOG,1.23,4.56,NYSE" 'http://localhost:8428/api/v1/import/csv?format=2:metric:ask,3:metric:bid,1:label:ticker,4:label:market'

Cluster:

curl --data-binary "@import.txt" -X POST  'http://<vminsert>:8480/insert/0/prometheus/api/v1/import/csv'
curl -d "GOOG,1.23,4.56,NYSE" 'http://<vminsert>:8480/insert/0/prometheus/api/v1/import/csv?format=2:metric:ask,3:metric:bid,1:label:ticker,4:label:market'

Additional information:

• URL format
• How to import CSV data

/api/v1/labels

Get a list of label names

Single:

curl -G 'http://localhost:8428/prometheus/api/v1/labels'

Cluster:

curl -G 'http://<vmselect>:8481/select/0/prometheus/api/v1/labels'

Additional information:

• Prometheus querying API usage
• Querying label values

/api/v1/label/<label_name>/values

Querying label values

Single:

curl -G 'http://localhost:8428/prometheus/api/v1/label/job/values'

Cluster:

curl -G 'http://<vmselect>:8481/select/0/prometheus/api/v1/label/job/values'

Additional information:

• Getting label names

/api/v1/query

Performs PromQL/MetricsQL instant query

Single:

curl -G 'http://localhost:8428/prometheus/api/v1/query?query=vm_http_request_errors_total&time=2021-02-22T19:10:30.781Z'

Cluster:

curl -G 'http://<vmselect>:8481/select/0/prometheus/api/v1/query?query=vm_http_request_errors_total&time=2021-02-22T19:10:30.781Z'

Additional information:

• Prometheus querying API usage
• Instant queries
• Query language

/api/v1/query_range

Performs PromQL/MetricsQL range_query

Single:

curl -G 'http://localhost:8428/prometheus/api/v1/query_range?query=vm_http_request_errors_total&start=2021-02-22T19:10:30.781Z&step=20m'

Cluster:

curl -G 'http://<vmselect>:8481/select/0/prometheus/api/v1/query_range?query=vm_http_request_errors_total&start=2021-02-22T19:10:30.781Z&step=20m'

curl -G 'http://<vmselect>:8481/select/0/prometheus/api/v1/query_range?query=vm_http_request_errors_total&start=-1h&step=10m'

curl -G http://<vmselect>:8481/select/0/prometheus/api/v1/query_range --data-urlencode 'query=sum(increase(vm_http_request_errors_total{status=""}[5m])) by (status)'

Additional information:

• Prometheus querying API usage
• Range queries
• Query language

/api/v1/series

Finding series by label matchers

Single:

curl -G 'http://localhost:8428/prometheus/api/v1/series?match[]=vm_http_request_errors_total&start=-1h'

Cluster:

curl -G 'http://<vmselect>:8481/select/0/prometheus/api/v1/series?match[]=vm_http_request_errors_total&start=-1h'

Additional information:

• Prometheus querying API usage
• Finding series by label matchers

/api/v1/status/tsdb

Cardinality statistics

Single:

curl -G 'http://localhost:8428/prometheus/api/v1/status/tsdb'

Cluster:

curl -G 'http://<vmselect>:8481/select/0/prometheus/api/v1/status/tsdb'

Additional information:

• Prometheus querying API usage
• TSDB Stats

/api/v1/targets

Checking targets

Should be sent to vmagent/VMsingle

Single:

curl -G 'http://<vmsingle>:8428/api/v1/targets' 

curl -G 'http://<vmagent>:8429/api/v1/targets' 

Additional information:

• Prometheus querying API usage
• Targets

/datadog/api/v1/series

Sends data from DataDog agent to VM

Single:

echo '
{
  "series": [
    {
      "host": "test.example.com",
      "interval": 20,
      "metric": "system.load.1",
      "points": [[
        0,
        0.5
      ]],
      "tags": [
        "environment:test"
      ],
      "type": "rate"
    }
  ]
}
' | curl -X POST --data-binary @- http://localhost:8428/datadog/api/v1/series

Cluster:

echo '
{
  "series": [
    {
      "host": "test.example.com",
      "interval": 20,
      "metric": "system.load.1",
      "points": [[
        0,
        0.5
      ]],
      "tags": [
        "environment:test"
      ],
      "type": "rate"
    }
  ]
}
' | curl -X POST --data-binary @- 'http://<vminsert>:8480/insert/0/datadog/api/v1/series'

Additional information:

• How to send data from datadog agent

/federate

Returns federated metrics

Single:

curl -G 'http://localhost:8428/federate?match[]=vm_http_request_errors_total&start=2021-02-22T19:10:30.781Z'

Cluster:

curl -G 'http://<vmselect>:8481/select/0/prometheus/federate?match[]=vm_http_request_errors_total&start=2021-02-22T19:10:30.781Z'

Additional information:

• Federation
• Prometheus-compatible federation data

/graphite/metrics/find

Searches Graphite metrics in VictoriaMetrics

Single:

curl -G 'http://localhost:8428/graphite/metrics/find?query=vm_http_request_errors_total'

Cluster:

curl -G 'http://<vmselect>:8481/select/0/graphite/metrics/find?query=vm_http_request_errors_total'

Additional information:

• Metrics find
• How to send data from graphite compatible agents such as statsd
• URL Format

/influx/write

Writes data with InfluxDB line protocol to VictoriaMetrics

Single:

curl -d 'measurement,tag1=value1,tag2=value2 field1=123,field2=1.23' -X POST 'http://localhost:8428/write'

Cluster:

curl -d 'measurement,tag1=value1,tag2=value2 field1=123,field2=1.23' -X POST 'http://<vminsert>:8480/insert/0/influx/write'

Additional information:

• How to send data from influxdb compatible agents such as telegraf

TCP and UDP

How to send data from OpenTSDB-compatible agents to VictoriaMetrics

Turned off by default. Enable OpenTSDB receiver in VictoriaMetrics by setting -opentsdbListenAddr command-line flag. If run from docker, '-opentsdbListenAddr' port should be exposed

Single:

echo "put foo.bar.baz `date +%s` 123 tag1=value1 tag2=value2" | nc -N localhost 4242

Cluster:

echo "put foo.bar.baz `date +%s` 123  tag1=value1 tag2=value2 VictoriaMetrics_AccountID=0" | nc -N http://<vminsert> 4242

Enable HTTP server for OpenTSDB /api/put requests by setting -opentsdbHTTPListenAddr command-line flag.

Single:

curl -H 'Content-Type: application/json' -d '[{"metric":"foo","value":45.34},{"metric":"bar","value":43}]' http://localhost:4242/api/put

Cluster:

curl -H 'Content-Type: application/json' -d '[{"metric":"foo","value":45.34},{"metric":"bar","value":43}]'
 'http://<vminsert>:8480/insert/42/opentsdb/api/put'

Additional information:

• Api http put
• How to send data from opentsdb compatible agents

How to write data with Graphite plaintext protocol to VictoriaMetrics

Enable Graphite receiver in VictoriaMetrics by setting -graphiteListenAddr command-line flag.

Single:

echo "foo.bar.baz;tag1=value1;tag2=value2 123 `date +%s`" |
 nc -N localhost 2003

Cluster:

echo "foo.bar.baz;tag1=value1;tag2=value2;VictoriaMetrics_AccountID=42 123 `date +%s`" | nc -N http://<vminsert> 2003

Additional information:

VictoriaMetrics_AccountID=42 - tag that indicated tenant ID.

• Request handler
• How to send data from graphite compatible agents such as statsd