API Reference

Stream Listing Updates

Server-Sent Events stream that delivers cached data immediately, then attempts a live fetch. Events arrive in this order: cached, then live or error, then done. A listing with no stored URL gets neither live nor error.

error carries a machine-readable code when the fetch itself fails: fetch_failed, upstream_unavailable, upstream_rate_limited, proxy_auth_failed, budget_exceeded, service_disabled, or cancelled (the 60-second stream limit was reached). A page that was fetched but could not be read sends error with only a message. Live fetches draw on a shared live-fetch budget: when it is held for Borough’s scheduled updates or live fetching is paused, the live attempt ends with error (budget_exceeded or service_disabled) and the cached event stands.

The cached payload is labelled source: "cache". live carries only the fields read from the live page, plus source: "live" and fetchedAt, so merge it over cached. Each connection costs one request against your quota and one live fetch: close the connection on done rather than letting an SSE client reconnect automatically.

Tier: Pro+

GET

listing

{id}

Stream listing updates (SSE)

curl --request GET \
  --url https://borough.qwady.app/v1/listing/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://borough.qwady.app/v1/listing/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://borough.qwady.app/v1/listing/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://borough.qwady.app/v1/listing/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://borough.qwady.app/v1/listing/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

Overview

Opens a Server-Sent Events (SSE) stream for a single listing. The stream delivers cached data immediately, then attempts a live fetch for fresher data when live fetching is available. Tier requirement: Pro, Business, or Internal.

SSE Events

Event	Description
`cached`	Immediate response from D1 cache (arrives within milliseconds). Carries `id`, `dataAge` and `source: "cache"`.
`live`	Fresh data read from the live listing page (usually a few seconds). Carries only the fields that could be read, plus `source: "live"` and `fetchedAt`; merge it over `cached`.
`error`	The live step could not complete. The payload carries a `message` and, when the fetch itself failed, a `code` (see below). A page that was fetched but could not be read has no `code`.
`done`	Stream complete, connection will close

Error codes

`code`	Meaning
`budget_exceeded`	Live fetching is being held back to protect Borough’s scheduled updates. The `cached` event stands; try again later.
`service_disabled`	Live fetching is temporarily paused. The `cached` event stands.
`upstream_unavailable`	The listing page could not be reached (retried once).
`upstream_rate_limited`	The listing page is rate-limiting requests (retried once).
`cancelled`	The 60-second stream limit was reached before live data arrived.
`proxy_auth_failed`	Borough’s live-fetch service rejected its credentials.
`fetch_failed`	Any other fetch failure.

Example

curl -N -H "Authorization: Bearer BOROUGH-..." \
  -H "Accept: text/event-stream" \
  https://borough.qwady.app/v1/listing/4961849

event: cached
data: {"id":"4961849","price":3200,"status":"ACTIVE",...,"dataAge":"2026-02-12T14:30:00Z","source":"cache"}

event: live
data: {"price":3150,"status":"ACTIVE",...,"source":"live","fetchedAt":"2026-02-12T16:05:03Z"}

event: done
data: {"complete":true}

When live fetching is held back, the live step ends with an error and the cached event is the answer:

event: cached
data: {"id":"4961849","price":3200,"status":"ACTIVE",...}

event: error
data: {"code":"budget_exceeded","message":"Live fetch budget is temporarily exhausted"}

event: done
data: {"complete":true}

Behavior

The cached event is always sent first (from D1 database)
The live event is sent if the live fetch succeeds (usually a few seconds)
If the live fetch fails, times out, or is held back (budget_exceeded or service_disabled), an error event is sent instead of live
A listing with no stored page URL skips the live step: cached is followed directly by done
The stream always ends with a done event, and the whole stream is capped at 60 seconds
Each connection costs one request against your quota and one live fetch. Close your client on done; an SSE client that reconnects automatically (such as a browser EventSource) re-opens the stream and is billed again each time

When to use

This endpoint is designed for one-time fresh data retrieval. For ongoing monitoring, use persistent watchers instead. Note: Business and Internal tier users get live-first data on the regular GET /v1/property/{id} endpoint (returned with "source": "live" when the stored detail is more than 5 minutes old and live fetching is available), so the SSE stream is primarily useful for Pro tier users who want live data.

Authorizations

Authorization

string

header

required

Polar.sh license key. Format: BOROUGH-<uuid>

Path Parameters

string

required

Listing ID

Response

Server-Sent Events stream

The response is of type string.

Stream listing updates (SSE)

curl --request GET \
  --url https://borough.qwady.app/v1/listing/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://borough.qwady.app/v1/listing/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://borough.qwady.app/v1/listing/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://borough.qwady.app/v1/listing/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://borough.qwady.app/v1/listing/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

Getting Started

Guides

Reference

API Reference

MCP Server

SDK

Stream Listing Updates

Overview

SSE Events

Error codes

Example

Behavior

When to use

Authorizations

Path Parameters

Response

​Overview

​SSE Events

​Error codes

​Example

​Behavior

​When to use

Authorizations

Path Parameters

Response

Overview

SSE Events

Error codes

Example

Behavior

When to use