Haul.FM API
Now playing, history and schedule for your own apps.
Show what Haul.FM is playing in your own app: a studio clock, an OBS overlay for your stream, your VTC website. Every answer is JSON, public data only, no key needed, open to every website (CORS).
- Base address:
https://haul.fm/api/v1 - Times are ISO 8601 in UTC; the schedule groups by days in Europe/Berlin.
- Please cache: every answer says for how long (Cache-Control). Polling more often than every 5 seconds does not make anything faster; use the event stream instead.
GET /now: on air
What plays right now, with cover, length and the presenter while a live show runs.
curl https://haul.fm/api/v1/now{
"status": "AUTO",
"type": "song",
"title": "Midnight Convoy",
"artist": "The Road Band",
"album": "Highway Nights",
"cover": { "300": "https://haul.fm/covers/3f2a…-300.webp", "600": "https://haul.fm/covers/3f2a…-600.webp",
"avif": { "300": "…-300.avif", "600": "…-600.avif" }, "source": "deezer" },
"durationSec": 215, "startedAt": "2026-11-05T19:58:12.000Z", "elapsedSec": 74,
"dj": null, "show": null, "liveUntil": null,
"next": { "title": "Open Road", "artist": "E2E Band" },
"updatedAt": "2026-11-05T19:59:24.000Z"
}| Field | Type | Meaning |
|---|---|---|
status | string | AUTO (the automation), LIVE (a presenter is on air), PAUSE (maintenance loop) or OFFLINE. |
type | string | null | song, show (a talk show) or station (news, traffic, jingles; no title). null while live without a song name. |
title, artist | string | null | The song. While live only when the presenter's software sends it. |
album | string | null | The album, when we know it. |
cover.300 / cover.600 | string | Our copy of the cover, square WebP, 300 or 600 px. |
cover.avif.300 / cover.avif.600 | string | The same as AVIF (smaller). |
cover.source | string | null | Where the picture came from: embedded (in the file), itunes or deezer. null when unknown. |
durationSec | number | null | Length in seconds (null while live). |
startedAt, elapsedSec | string, number | When it started and how far it is, at the time of the answer. |
dj, show, liveUntil | string | null | While live: the presenter, the show (when public) and the planned end. |
next | object | null | The next song of the automation, when it is announced. |
GET /history: last songs
The last 20 songs, newest first (songs only: no jingles, news or speech).
curl https://haul.fm/api/v1/history| Field | Type | Meaning |
|---|---|---|
items[].title, artist, album, startedAt | string | As in /now. |
items[].cover | object | null | As in /now. |
GET /schedule: the next two weeks
Live shows, talk shows and events of the next 14 days: what is on air now, what comes next, and every day (station time, Europe/Berlin). today and tomorrow stay for simple clocks.
curl https://haul.fm/api/v1/schedule| Field | Type | Meaning |
|---|---|---|
now, next | object | null | The show on air now and the next one. |
days[].date, today.date, tomorrow.date | string | YYYY-MM-DD. |
*.shows[].title, kind, hosts | string, string, string[] | kind: live (a presenter), talk (a talk show) or event. |
*.shows[].description, image | string | null | A short text and the presenter's picture (our URL). |
*.shows[].startsAt, endsAt, onAir | string, string, boolean | onAir: it runs right now. An event has no end: it counts three hours. |
The same shows as a calendar to subscribe to (Google, Apple, Outlook):
https://haul.fm/api/v1/schedule.ics
GET /stream: stream addresses
The stream for players and browsers (https) and the line for the in-game radio of Euro Truck Simulator 2 and American Truck Simulator.
curl https://haul.fm/api/v1/stream
GET /events: live updates
A Server-Sent Events stream: one event right away (now), then track when the song changes and status when the station switches (AUTO, LIVE, presenter). Each carries the same object as /now. A comment line every 25 seconds keeps the connection open; browsers reconnect by themselves.
const events = new EventSource("https://haul.fm/api/v1/events");
events.addEventListener("now", (e) => show(JSON.parse(e.data)));
events.addEventListener("track", (e) => show(JSON.parse(e.data)));
events.addEventListener("status", (e) => show(JSON.parse(e.data)));
function show(now) {
document.querySelector("#title").textContent = now.title ? `${now.artist} – ${now.title}` : "Haul.FM";
document.querySelector("#cover").src = now.cover?.["300"] ?? "/logo.png";
}Without a browser:
curl -N https://haul.fm/api/v1/events
JavaScript
const now = await fetch("https://haul.fm/api/v1/now").then((r) => r.json());
console.log(now.status, now.artist, now.title, now.elapsedSec + "/" + now.durationSec);
Limits
- 120 requests a minute per address, 3 open event streams per address. Over it: HTTP 429 with Retry-After.
- Headers X-RateLimit-Limit and X-RateLimit-Remaining show where you are.
- Covers come from our own server; please link them, do not copy them into other services.
Partner token (studio apps)
Studio clocks and tools of our team and partners get a token from the Haul.FM team. It raises the limits (600 a minute, 10 streams) and adds studio fields. Send it as a header, or as ?token= for the event stream (EventSource cannot send headers). Keep it secret; a revoked or wrong token gets HTTP 401.
curl -H "Authorization: Bearer hfm_…" https://haul.fm/api/v1/now
new EventSource("https://haul.fm/api/v1/events?token=hfm_…") // adds the event "studio"| Field | Type | Meaning |
|---|---|---|
studio.onAir | boolean | ON AIR: a presenter is on air. OFF AIR otherwise (also while connected and waiting). |
studio.live.connected, state, dj | boolean, string, string | The live input: connected, its state (standby, live, ending …) and the presenter. |
studio.silence.station | boolean | The station's output has been silent in two checks in a row. |
studio.silence.presenter, presenterSec | boolean, number | The presenter's input is silent for 5 seconds or more, and for how long. |
studio.next | object | null | The next fixed date: a show of the programme or an event (kind, title, startsAt, endsAt). |
Fair use
Free for fan sites, streamers, VTCs and tools. Name Haul.FM and link haul.fm where you show the data. We may change or switch off the API; breaking changes get a new version (/api/v2).