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. A single stream lasts at most 5 minutes and then sends reconnect; open a new one to continue. stopped means the watcher was paused or deleted.

Every event carries an SSE id — a resume cursor. 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

"<string>"

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, or quota-exhausted).

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. The stream requires Business or Internal tier, and returns 400 if the watcher is paused.

Resuming

Every change, heartbeat, and reconnect 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

"<string>"

Getting Started

Guides

Reference

API Reference

MCP Server

SDK

Stream Watcher Changes

SSE Events

Resuming

Authorizations

Path Parameters

Query Parameters

Response

​SSE Events

​Resuming

Authorizations

Path Parameters

Query Parameters

Response

SSE Events

Resuming