How to manage Prometheus jobs and targets via API

General

You can manage your Prometheus scrape configurations (jobs and targets) using the Observability API.

For a complete list of all available endpoints, parameters, and schemas, refer to the STACKIT Observability Scrape Config API Specification.

To execute the following commands, you need to set your PROJECT_ID and INSTANCE_ID as environment variables (or replace them directly in the commands).

If you need help locating these identifiers or want to learn how the stackit curl wrapper handles authentication automatically, refer to our central guide: Interacting with the Observability API.

How to create a Prometheus job and target

To configure your first job and target, send an HTTP POST request to the scrapeconfigs endpoint. With the following request body, you have the minimal configuration of a new job and target.

Command:

stackit curl -X POST "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/scrapeconfigs" \
  -H "Content-Type: application/json" \
  --data '{"staticConfigs":[{"targets":["your-url-which-delivers-your-metrics.com:9100"]}],"jobName":"Job-1","scheme":"http","scrapeInterval":"5m","scrapeTimeout":"2m","metricsPath":"/metrics"}'

How to change a Prometheus job and target

To modify an existing job and target, use the HTTP PATCH method instead of POST and specify the specific <JOB_NAME> in the URL.

With the following command, your job and target will be updated to use the new URL, a 15-minute scrape interval, and a 1-minute scrape timeout.

Command:

stackit curl -X PATCH "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/scrapeconfigs/<JOB_NAME>" \
  -H "Content-Type: application/json" \
  --data '{"staticConfigs":[{"targets":["your-changed-url-which-delivers-your-metrics.com:9100"]}],"jobName":"Job-1","scheme":"http","scrapeInterval":"15m","scrapeTimeout":"1m","metricsPath":"/metrics"}'

How to delete a Prometheus Job

To delete a job, specify the job name you want to delete in the URL and send an HTTP DELETE request.

Command:

stackit curl -X DELETE "https://argus.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/instances/$INSTANCE_ID/scrapeconfigs/<JOB_NAME>" \
  -H "accept: application/json"

How to delete a Prometheus Target

You cannot use the DELETE request to remove a specific target, as it will delete the entire job. To delete a target, you must execute a PATCH request (as shown in the “How to change a Prometheus job and target” section) and omit the target you want to delete from the targets array in your request body.