Hosting edition
Metrics, reports and locations
Scrape per-station Prometheus metrics, export the listener sessions and song plays that royalty collecting societies ask for, and see which countries listeners are in.
All three are part of the Hosting edition. The open-source core has the status endpoints instead.
Prometheus metrics#
GET /metrics returns Prometheus text. It accepts the hosting API token as a bearer token, or the admin account with basic authentication.
curl -H "Authorization: Bearer $TOKEN" https://radio.example/metrics
Every metric is a gauge.
| Metric | Labels | Value |
|---|---|---|
lurcast_uptime_seconds |
none | Seconds since the server started. |
lurcast_listeners |
mount, station |
Connected listeners per mount. |
lurcast_source_connected |
mount, station |
1 when a source is connected. |
lurcast_bitrate_kbps |
mount, station |
Stream bitrate in kbps. |
lurcast_station_month_bytes_sent |
station |
Bytes sent to listeners this month (UTC). |
lurcast_station_month_listener_seconds |
station |
Listening time this month (UTC). |
lurcast_station_transfer_quota_bytes |
station |
Monthly transfer quota. Absent when the station has no quota. |
lurcast_station_suspended |
station |
1 when the station is suspended. |
lurcast_license_expiry_timestamp_seconds |
none | When the license expires, as a Unix timestamp. |
The per-mount metrics carry a station label only for mounts that belong to a provisioned station; other mounts, such as relays from the configuration file, have only mount.
lurcast_listeners{mount="/rockfm",station="rockfm"} 87
lurcast_station_month_bytes_sent{station="rockfm"} 52428800000
lurcast_station_transfer_quota_bytes{station="rockfm"} 107374182400
Scrape configuration#
Store the API token in a file Prometheus can read, then:
scrape_configs:
- job_name: lurcast
scheme: https
authorization:
type: Bearer
credentials_file: /etc/prometheus/lurcast-token
static_configs:
- targets: ["radio.example:443"]
Alerts worth having#
groups:
- name: lurcast
rules:
- alert: LurcastLicenseExpiresSoon
expr: lurcast_license_expiry_timestamp_seconds - time() < 7 * 86400
labels:
severity: warning
- alert: LurcastStationNearQuota
expr: lurcast_station_month_bytes_sent / lurcast_station_transfer_quota_bytes > 0.9
labels:
severity: info
Automatic renewal starts 10 days before expiry, so a license that is still within 7 days of expiry usually means renewal is failing. See Licensing and renewal.
Royalty reports#
The server logs every listener session and every song change to CSV files, one pair per station and month:
<data_dir>/reports/<station>/<YYYY-MM>-sessions.csv
<data_dir>/reports/<station>/<YYYY-MM>-plays.csv
Download them through the API, or read them from disk:
curl -H "Authorization: Bearer $TOKEN" -o rockfm-2026-11-sessions.csv \
'https://radio.example/api/hosting/v1/stations/rockfm/reports/sessions.csv?month=2026-11'
curl -H "Authorization: Bearer $TOKEN" -o rockfm-2026-11-plays.csv \
'https://radio.example/api/hosting/v1/stations/rockfm/reports/plays.csv?month=2026-11'
sessions.csv#
One row per listener session, written when the listener disconnects.
| Column | Contents |
|---|---|
started_at, ended_at |
RFC 3339 timestamps. |
duration_seconds |
Length of the session. |
bytes_sent |
Bytes sent to this listener. |
ip |
Listener address, truncated to /24 (IPv4) or /48 (IPv6) while anonymize_ips is on. |
user_agent |
The player's user agent. |
listener_id |
The server's ID for the connection. |
mount |
The mount listened to. |
country |
The listener's country code, such as SE, when listener locations are on. Empty otherwise. |
plays.csv#
One row per song change, from the source's metadata.
| Column | Contents |
|---|---|
played_at |
RFC 3339 timestamp. |
artist, title |
Split from Artist - Title. If the title has no -, artist is empty. |
raw_title |
The metadata exactly as the source sent it. |
listeners |
Listeners connected when the song started. |
Plays are only as good as the metadata your customers' encoders send.
Monthly summary#
GET /api/hosting/v1/stations/{id}/reports/summary?month=YYYY-MM totals the month:
- Aggregate tuning hours: the sum of all session durations, in hours.
- Total performances: the sum of listeners across every play.
{
"station": "rockfm",
"month": "2026-11",
"summary": {
"sessions": 4210,
"aggregate_tuning_hours": 1820.5,
"plays": 3150,
"total_performances": 61240
}
}
These are the figures most collecting societies, such as SoundExchange, PRS and STIM, ask for. Each society has its own template and rules, so check them before you submit.
Listener locations#
Point the Hosting edition at a country database to see where listeners are:
hosting:
geoip_database: /var/lib/lurcast/dbip-country-lite.mmdb
Any country database in MaxMind DB format (.mmdb) works:
- DB-IP IP to Country Lite: free under CC BY 4.0, with no account. Download the
.mmdbfrom db-ip.com. It is updated monthly. - MaxMind GeoLite2 Country: free with a MaxMind account.
Each listener's country is looked up on your server when they connect. No listener address is sent anywhere, and only the country is kept, never the city. The lookup uses the full address, so sessions.csv can show listening per country even while anonymize_ips truncates the address in the ip column. The country appears:
- in the admin dashboard: a Listener locations panel for the whole server, a Where listeners are chart per mount, and a country column in the listener list
- in the
countrycolumn ofsessions.csv, for collecting societies that ask for listening by territory - in the
listener.connectedandlistener.disconnectedwebhooks

To update the database, replace the file and reload the configuration (Reload config in the dashboard, or systemctl reload). Behind a reverse proxy, set trusted_proxies so the listener's own address is looked up, not the proxy's.
Session files started before the country column existed keep their original columns until the next month begins.