API Reference

Stream Watcher Changes

Opens a Server-Sent Events stream that delivers a watcher’s change events as its scheduled polls detect them. The stream emits exactly these events: connected, change, heartbeat, reconnect, and stopped.

Delivery is decoupled from the watcher’s pollInterval: the watcher polls upstream on its own schedule, while the stream drains whatever it has found every 20 seconds, sending heartbeat on a tick with nothing new. If the watcher is briefly unavailable, the stream stays open and heartbeats pause until it recovers, so a missing heartbeat does not mean the connection has dropped. A single stream lasts at most 5 minutes and then sends reconnect; open a new one to continue. stopped means the watcher is no longer active: paused, deleted, stopped because the monthly quota ran out, or paused because the account dropped below Business. If the stream closes without an event, reconnect with your last id. Each stream connection, including every reconnect after the 5-minute limit, counts as one request against your quota: about 12 an hour, or about 8,640 per 30 days, for a stream kept open continuously, on top of the polls.

Every change, heartbeat, reconnect and stopped event carries an SSE id, a resume cursor; connected does not. Reconnect with the standard Last-Event-ID header, or with since on a first connect where the client cannot set headers.

Tier: Business+

GET

watchers

{id}

stream

Stream watcher changes (SSE)

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

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

fetch('https://borough.qwady.app/v1/watchers/{id}/stream', 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/watchers/{id}/stream",
  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/watchers/{id}/stream"

	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/watchers/{id}/stream")

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

SSE Events

The stream emits exactly five event types:

Event	Description
`connected`	Stream opened. Payload carries `watcherId`, `watchType`, `targetId`, `pollInterval`.
`change`	A change was detected. Payload carries `eventType`, `listingId`, `oldValue`, `newValue`.
`heartbeat`	Keep-alive: the stream checked for new changes and found none. Payload carries `timestamp`.
`reconnect`	The 5-minute stream lifetime was reached. Reconnect to continue.
`stopped`	The watcher is no longer active: paused, deleted, stopped because the monthly quota ran out, or paused because the account dropped below Business. After re-subscribing, resume it with `PATCH /watchers/{id}` and `{"active": true}`.

heartbeat is a connection keep-alive on the stream’s own short drain cadence. It is not tied to the watcher’s pollInterval and does not mean an upstream poll just completed. If the watcher is briefly unavailable, the stream stays open and heartbeats pause until it recovers, for at most the rest of the stream’s 5-minute lifetime. The connection is still alive, so don’t treat a missing heartbeat as a dropped stream or reconnect because of one. The stream ends with reconnect or stopped, or when your client disconnects. The stream requires Business or Internal tier, and returns 400 if the watcher is paused.

Change events

The eventType on a change event, and what listingId, oldValue and newValue hold, depend on the watch type:

`eventType`	Watch type	`listingId`	`oldValue` → `newValue`
`listing.price_decreased`, `listing.price_increased`	listing	The listing	Old price → new price. Only moves of more than $25 are reported.
`listing.status_changed`	listing	The listing	Old status → new status
`listing.expired`	listing	The listing	Old status → `OFF_MARKET`
`listing.created`	building, search	The listing that appeared	`null` → the listing ID
`listing.expired`	building, search	The listing that left	The listing ID → `"removed"`. The listing left the watcher’s set of active matches: it went off market, or no longer matches (for example, its price moved out of your range). It has not necessarily expired.
`building.listings_changed`	building	The building ID, not a listing	`null` → `"cron_detected"`: Borough’s scheduled refresh saw a change among this building’s listings.

A listing watcher can also receive a change that Borough’s scheduled refresh detected for the same listing, so the same price or status change can arrive twice. De-duplicate on eventType and newValue. While live fetching is held back for Borough’s scheduled updates, or paused, a listing watcher skips its own polls, and skipped polls are not counted. Changes Borough’s scheduled refresh detects for the listing can still arrive; otherwise the stream sends only heartbeat events. No separate signal is sent.

Resuming

Every change, heartbeat, reconnect, and stopped event carries an SSE id: a cursor into the watcher’s change buffer, which retains the last 50 detected changes. Send that cursor back and the server resumes from it rather than from the current tip.

Last-Event-ID: <id> header — what browser EventSource and the Borough SDK replay automatically on reconnect. Wins if both are supplied.
?since=<id> query parameter — for a first connect from a client that cannot set request headers.

A connection with no cursor starts at the buffer tip, so it delivers only changes detected from that point on. The connected event carries no id. See the streaming guide for worked examples and the retention caveats.

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

Watcher ID (UUID)

Query Parameters

since

integer

Resume cursor — the SSE id of the last event you processed. Changes recorded after it are replayed, bounded by how many the watcher retains. Ignored when Last-Event-ID is present, which takes precedence. A connect with neither starts at the current tip instead of replaying.

Required range: x >= 0

Response

Server-Sent Events stream

The response is of type string.

Stream watcher changes (SSE)

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

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

fetch('https://borough.qwady.app/v1/watchers/{id}/stream', 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/watchers/{id}/stream",
  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/watchers/{id}/stream"

	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/watchers/{id}/stream")

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 Watcher Changes

SSE Events

Change events

Resuming

Authorizations

Path Parameters

Query Parameters

Response

​SSE Events

​Change events

​Resuming

Authorizations

Path Parameters

Query Parameters

Response

SSE Events

Change events

Resuming