Conventions

Response envelope. Every success is:

{ "ok": true, "data": { … }, "meta": { … } }

meta includes brokerageId, and where relevant range, granularity, coverage, total and nextCursor. Every error is:

{ "ok": false, "error": { "code": "invalid_range", "message": "…" }, "requestId": "req_…" }

Every response has an X-Request-Id header. Quote it when you contact support.

Dates and time zone. Timestamps are ISO 8601 in UTC (2026-09-30T02:19:03Z). Days, weeks and months are calendar periods in America/Chicago, the clock Ruuster's weekly analytics email uses.

Ranges. from and to are dates (YYYY-MM-DD). The range includes from and excludes to, so from=2026-09-21&to=2026-09-28 is Monday September 21 through Sunday September 27. Without them a call covers the last 30 complete days, unless the call's own page says otherwise. A reversed or oversized range returns 400 invalid_range.

Granularity. Series calls take granularity=day|week|month. Weeks start on Monday. Each bucket is labelled with its first day ("bucket": "2026-09-21"). A bucket cut off by your range is marked "partial": true.

Which date a list filters on. List calls take dateField to choose what from/to apply to:

Pagination. Lists return up to limit rows and meta.nextCursor. Pass the cursor back as ?cursor= for the next page; null means you're done. Cursors stay valid for at least 24 hours and work for any owner or admin key in your brokerage. There are no page numbers.

Coverage. meta.coverage says which days are available for your brokerage: from/to for Ruuster's own activity data, ga for Google Analytics data, ownershipAsOf for the last listing-attribution refresh, and stableBefore, the day before which numbers no longer change. Buckets outside coverage return null metrics, never 0. Totals are computed over covered buckets, and bucketsRequested / bucketsCovered show how many that was.

Comparing periods. Planned: compare=previous will add a previous object with the same shape for the range immediately before yours. Until then, request two periods and compare the buckets (see Guides).

Incremental sync. Planned: bulk calls will accept changedSince=<timestamp> and return only records whose numbers changed since then. Until then, re-pull the last few days on each sync.

Caching. Planned: responses for completed periods will carry an ETag. A matching If-None-Match will return 304 Not Modified with no body, which uses none of your daily row quota.

Methods. Every data call is GET. Other methods return 405 method_not_allowed with an Allow header. Webhook management uses POST, PATCH and DELETE as documented.

Identifiers

Versioning. Breaking changes ship as /v2; /v1 keeps working. Removing a field, changing what null means, or changing bucket boundaries counts as breaking. Adding fields, optional parameters, calls or event kinds doesn't; ignore fields you don't use. Ruuster announces deprecations at least 90 days ahead in the changelog and with Deprecation and Sunset headers.

About the examples

Fixture. Every example in these docs uses one fictional brokerage, "Saguaro Realty Group" (saguaro.ruuster.com), observed on Thursday 2026-10-01. All people, addresses, ids and numbers are fictional. Weeks are Monday–Sunday America/Chicago (2026-09-21 is a Monday).

The recipes in Guides use this shell setup:

B=https://api.ruuster.com/v1
H=(-H "x-api-key: $RUUSTER_API_KEY" -H "x-email: jane@saguarorealty.com")

Response headers on every authenticated call (shown once):

HTTP/2 200
content-type: application/json; charset=utf-8
cache-control: no-store
x-request-id: req_01J9ZB4M8Q2C7V5T3K8P6W1N0X
x-ratelimit-limit: 120
x-ratelimit-remaining: 117
x-ratelimit-reset: 1790863260
x-daily-rows-limit: 250000
x-daily-rows-remaining: 248310

Lead email/phone appear in these examples because the fixture brokerage has lead contact details enabled. With them disabled, those two fields are omitted from every lead object. Property objects also carry mlsName and mlsRecordIdCore; they're left out of the examples for length.