Docs

Volcengine Managed Service for Prometheus

Writing and querying workspace data

Accessing VMP query APIs via curl

This topic provides complete, ready-to-run curl examples and is intended for users who need to access VMP workspaces via curl. This access method supports BasicAuth authentication. This topic details access methods for the query APIs, covering instant queries, range queries, time series queries, and label key/value queries. Applicable scenarios include API integration testing, script integration, and O&M troubleshooting.

Prerequisites

Before you make calls, prepare the following information:

A VMP workspace and its query URL (query_url). For details on obtaining query URLs, see Obtaining workspace URLs.

BasicAuth username/password: The BasicAuth account and password configured on the workspace details page. These credentials will be used for BasicAuth authentication to access the workspace.

Dependencies and environment variables:

Dependency	Purpose	Required
curl	Sends HTTP requests	Yes
base64	Serves as a tool for manually constructing a BasicAuth request header	No
jq	Formats JSON responses for readability	No

Configure environment variables in Shell:

export VMP_QUERY_URL="https://your-vmp-query-endpoint"
export VMP_USERNAME="your_basic_auth_username"
export VMP_PASSWORD="your_basic_auth_password"

Query examples

API descriptions and call examples

API path	Typical purpose	Description
/api/v1/query	Instant query	Queries the current value at a specific time point.
/api/v1/query_range	Range queries	Queries data within a specified time period to reflect trends.
/api/v1/series	Queries matching time series	Suitable for confirming whether a metric or label combination exists.
/api/v1/labels	Queries label keys	Suitable for querying available labels in the current workspace.
/api/v1/label/<name>/values	Queries label values	Suitable for querying the set of existing values for a specific label key.

tip

Key fields in responses to API calls are described as follows:

status: Indicates whether the request is successful.

data.resultType: Indicates the result type.

data.result: Contains the actual metric query result.

Instant queries

Range queries

Time series queries

Label key queries

Label value queries

FAQ and troubleshooting suggestions

Q1: Why does authentication fail with the 401 or 403 error?

Possible causes:

The BasicAuth username or password is incorrect.

The requested workspace URL is invalid.

The current account lacks access permission for the target workspace.

Troubleshooting suggestions:

Use a query command to verify connectivity.

Confirm whether the credentials in --user "$VMP_USERNAME:$VMP_PASSWORD" are correct.

Q2: Why do queries succeed but return empty results?

Possible causes:

The PromQL query did not match any data.

The query time range is too narrow.

Written metric data has not been synchronized to the query side.

Troubleshooting suggestions:

Use a simpler metric name.

Expand the time range (for example, from the last 5 minutes to the last 30 minutes).

Wait 5 to 10 minutes and then retry the query.

Q3: Why is the command output unreadable despite successful execution?

Possible causes:

The results are returned as compressed single-line JSON.

The jq tool has not been installed on the local system, so the output cannot be formatted.

Troubleshooting suggestions:

Add | jq to the end of the command.

If the jq tool is not installed locally, temporarily remove this command and install the tool after confirming the API is available.

Last updated: 2026.10.10 11:04:51