Scrape Prometheus metrics

How-to guide

For:: Developers

HostRepute publishes your team’s totals as Prometheus email reputation metrics at GET /api/v1/metrics: how many domains and IPs you monitor and how many are listed on a blocklist, how many certificates aren’t valid, your credit balance and more. Point a Prometheus server, or any scraper that reads the Prometheus text format, at it to graph them and alert on them next to your other monitoring.

Before you begin

A Business or Enterprise plan on the team whose metrics you want. Each team has its own metrics and needs its own token.
The Developer role or higher, to create an API token. Read Authentication and API tokens.
A Prometheus server that can reach https://app.hostrepute.com.

Create a token for Prometheus

Open Settings, then API tokens and choose Create a token.
Name the token, for example “Prometheus”. A new token starts with every read and check ability ticked, and check abilities start checks that use credits. A scraper needs only metrics:read, so choose Clear, then tick Read under Metrics.
Choose Create token and copy the token. It’s only shown once.

Try it before you set up Prometheus:

curl -s https://app.hostrepute.com/api/v1/metrics \
  -H "Authorization: Bearer $HOSTREPUTE_TOKEN"

# HELP hostrepute_hosts_total Total non-temporary hosts.
# TYPE hostrepute_hosts_total gauge
hostrepute_hosts_total{team="01JZ8Q6W3T2M7XKD4R5N9BVC1E"} 8
# HELP hostrepute_hosts_blocklisted Currently blocklisted non-temporary hosts.
# TYPE hostrepute_hosts_blocklisted gauge
hostrepute_hosts_blocklisted{team="01JZ8Q6W3T2M7XKD4R5N9BVC1E"} 2

The response is text/plain; version=0.0.4; charset=utf-8, the Prometheus text format, not JSON.

Configure Prometheus

Add a scrape job to prometheus.yml. The authorization block sends the token as Authorization: Bearer <token> (Prometheus configuration, checked October 2026):

scrape_configs:
  - job_name: hostrepute
    scheme: https
    metrics_path: /api/v1/metrics
    scrape_interval: 5m
    authorization:
      type: Bearer
      credentials: YOUR_API_TOKEN
    static_configs:
      - targets: ['app.hostrepute.com']

To keep the token out of prometheus.yml, put it in a file and replace credentials with credentials_file: /etc/prometheus/hostrepute-token.
Every scrape counts toward your team’s 120 API requests a minute (see Rate limits). Most values change only when HostRepute runs a check, blocklist checks at most every 30 minutes, so a 5-minute interval is enough.
Check the file with promtool check config prometheus.yml, then reload Prometheus.

What each metric means

Every metric is a gauge with one label, team, holding your team’s ID (the ULID in your portal URLs). Prometheus adds its own job and instance labels.

Metric	What it counts
`hostrepute_hosts_total`	Domains and IPs on Domains & IPs, paused ones included. The temporary ones a manual scan adds don’t count.
`hostrepute_hosts_blocklisted`	Of those, the ones HostRepute currently counts as listed on a blocklist.
`hostrepute_certificate_monitors_total`	Certificates on the Certificates page.
`hostrepute_certificate_monitors_unhealthy`	Certificates whose status isn’t Valid: Not checked yet, Expiring soon, Expired, Not trusted or Couldn’t connect.
`hostrepute_credits_balance`	The team’s credit balance.
`hostrepute_alert_destinations_total`	Alert channels, paused ones included.
`hostrepute_snds_integrations_total`	Microsoft SNDS connections.
`hostrepute_gmail_postmaster_integrations_total`	Google accounts connected to Google Postmaster Tools.
`hostrepute_deliverability_checks_total`	Email authentication checks HostRepute has stored for the team: scheduled and one-off, from the portal, the API or MCP.
`hostrepute_deliverability_failures_total`	Of those, the checks whose overall result is failed.

The names keep the API’s internal words: hosts are domains and IPs, alert_destinations alert channels, integrations connections and deliverability email authentication. Names ending in _total are gauges too, not counters, so use their values as they are rather than with rate() or increase().

Alert on the metrics

HostRepute already sends its own alerts to your alert channels. To alert from Prometheus instead, load a rules file with rule_files in prometheus.yml. This one fires when a domain or IP stays listed for 30 minutes, and when credits run low:

groups:
  - name: hostrepute
    rules:
      - alert: HostReputeListed
        expr: hostrepute_hosts_blocklisted > 0
        for: 30m
        labels:
          severity: critical
        annotations:
          summary: '{{ $value }} domains or IPs are listed on a blocklist'
      - alert: HostReputeCreditsLow
        expr: hostrepute_credits_balance < 100
        labels:
          severity: warning
        annotations:
          summary: 'Only {{ $value }} HostRepute credits left'

Check it with promtool check rules hostrepute-rules.yml.

Check that it worked

In Prometheus, the query up{job="hostrepute"} returns 1.
The query hostrepute_hosts_total returns one series with your team’s team label and the number of domains and IPs the portal shows.

Troubleshooting

403 with "This action is unauthorized." The team isn’t on the Business or Enterprise plan, or the token lacks metrics:read. The answer is the same for both, so check the plan in Plans and billing and the token’s abilities.
401 with "Unauthenticated." The token is wrong, revoked or expired, or the authorization block is missing.
429. Your team made more than 120 API requests in a minute, scrapes included. Scrape less often, or slow down other API clients that use the same team.
The numbers belong to another team. A token reaches only the team it was created in. Compare the team label with the ULID in your portal’s URLs, and create a token in the right team.