# List listings Source: https://help.ruuster.com/api/properties-list ```http GET https://api.ruuster.com/v1/properties ``` Listings attributed to your brokerage, including listings that left the market in about the last 18 months. Also finds a listing by MLS number. - Authentication: `x-api-key` and `x-email` headers of an owner or admin - Rate limit: 120 requests per minute per key ## Query parameters | Name | Type | Default | Description | |---|---|---|---| | `status` | string | `active` | `active` (Active, Coming Soon), `pending` (Pending, Under Contract, Contingent), `closed` or `all` | | `mlsRecordId` | string | | Find by MLS number, with or without its leading letters. Searches your listings only and adds `ambiguous` to the response. See [MLS numbers](https://help.ruuster.com/api/mls-numbers) | | `mlsId` | string | | Limit to one of your MLSs (see `mlsIds` in `/me`) | | `matchSource` | string | | `agent` (the listing agent's MLS id is on one of your agents' profiles), `office` (an office Ruuster confirmed as yours) or `both` | | `dateField` | string | `updated` | Which date `from` and `to` filter on: `updated` (record changed), `onMarket` or `closed` | | `from` | date | | First day, `YYYY-MM-DD`, included. No date filter when omitted | | `to` | date | | Day after the last day, `YYYY-MM-DD`, excluded | | `cursor` | string | | `meta.nextCursor` from the previous page. Omit for the first page | | `limit` | integer | `100` | Rows per page, 1 to 500 | | `countOnly` | `0` \| `1` | `0` | `1` returns `{ "total": n }` and no rows | | `agent` | string | your default agent | Whose page the listing links (`url`) open under: an `agentId`, email or landing-page slug from [List agents](https://help.ruuster.com/api/agents-list). Whoever signs up from such a link becomes that agent's lead. Without it, links credit your brokerage's default agent (where unassigned leads go). `meta.agent` names the agent credited | ## Response `data.properties` is a list of property objects. `meta.total` is the number of matching listings and `meta.nextCursor` pages through them. With `mlsRecordId`, `data.ambiguous` is `true` when the digits matched more than one of your listings; send the full number or add `mlsId` to pick one. ## Property object | Field | Description | |---|---| | `propertyId` | Ruuster's id for the listing (uuid), the id in `…/listings/` on your site | | `mlsId`, `mlsName` | The MLS the listing comes from | | `mlsRecordId` | MLS number as the MLS publishes it | | `mlsRecordIdCore` | The MLS number with its leading letters removed | | `address`, `city`, `state`, `postalCode`, `price` | Listing facts | | `status` | Ruuster status group: `active`, `pending`, `closed` or `other` | | `mlsStatus` | The MLS's own status | | `onMarketDate`, `closeDate` | Dates | | `listAgentMlsId`, `listOfficeMlsId` | From the MLS | | `matchSource` | Why it's attributed to your brokerage: `agent`, `office` or `both` | | `photoUrl`, `mediaCount` | Primary photo and number of photos | | `url` | The listing page on your Ruuster site, under an agent's page, `…/agent//listings/`, so whoever signs up from it becomes that agent's lead: the `agent` you pass, else your brokerage's default agent (where unassigned leads go). Every link in one response credits the same agent, named in `meta.agent`. The plain `…/listings/` when your brokerage has no default agent and you passed none | | `previousPropertyIds` | *Planned.* Earlier Ruuster ids when the listing was re-listed. `[]` until available | | `firstSeenAt`, `lastSeenAt` | When Ruuster first and last attributed the listing to you | | `mlsModifiedAt`, `updatedAt` | Last MLS change, and last change to this record | | `ownedByYou` | `true` for every listing here. Property objects from [Get a listing](https://help.ruuster.com/api/properties-get) and [Look up any listing by MLS number](https://help.ruuster.com/api/properties-lookup) can describe another brokerage's listing, with `ownedByYou: false` | ## Example request cURL: ```bash curl -s "https://api.ruuster.com/v1/properties?status=active&limit=2" \ -H "x-api-key: $RUUSTER_API_KEY" \ -H "x-email: $RUUSTER_EMAIL" ``` Node.js: ```javascript const res = await fetch("https://api.ruuster.com/v1/properties?status=active&limit=2", { headers: { "x-api-key": process.env.RUUSTER_API_KEY, "x-email": process.env.RUUSTER_EMAIL, }, }); const body = await res.json(); if (!body.ok) throw new Error(`${body.error.code}: ${body.error.message} (${body.requestId})`); console.log(body.data); ``` Python: ```python import os import requests res = requests.get( "https://api.ruuster.com/v1/properties?status=active&limit=2", headers={"x-api-key": os.environ["RUUSTER_API_KEY"], "x-email": os.environ["RUUSTER_EMAIL"]}, timeout=30, ) body = res.json() if not body["ok"]: raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]} ({body.get("requestId")})') print(body["data"]) ``` ## Example response ```json { "ok": true, "data": { "properties": [ { "propertyId": "5b7e2d94-1c63-4a8f-b5e0-9d3c7a2f1e86", "mlsId": "3f4a7b12-6c85-4d93-a1e0-8b2f5c9d7e31", "mlsRecordId": "22418765", "address": "4182 E Saguaro Bloom Dr", "city": "Tucson", "state": "AZ", "postalCode": "85718", "price": 489000, "status": "active", "mlsStatus": "Active", "onMarketDate": "2026-08-27", "closeDate": null, "listAgentMlsId": "28301", "listOfficeMlsId": "333802", "matchSource": "agent", "photoUrl": "https://cdn.example-mls.com/22418765/1.jpg", "mediaCount": 38, "url": "https://saguaro.ruuster.com/agent/jane-doe/listings/5b7e2d94-1c63-4a8f-b5e0-9d3c7a2f1e86", "previousPropertyIds": [], "firstSeenAt": "2026-08-27T15:02:11Z", "lastSeenAt": "2026-10-01T06:12:30Z", "mlsModifiedAt": "2026-09-29T19:41:00Z", "updatedAt": "2026-10-01T06:12:30Z" }, { "propertyId": "a03c8f61-7e2b-4d95-8a14-6f0b3e9c2d57", "mlsId": "3f4a7b12-6c85-4d93-a1e0-8b2f5c9d7e31", "mlsRecordId": "22419302", "address": "1920 W Mesquite Ridge Ln", "city": "Oro Valley", "state": "AZ", "postalCode": "85737", "price": 615000, "status": "active", "mlsStatus": "Active", "onMarketDate": "2026-09-10", "closeDate": null, "listAgentMlsId": "31877", "listOfficeMlsId": "333802", "matchSource": "both", "photoUrl": "https://cdn.example-mls.com/22419302/1.jpg", "mediaCount": 44, "url": "https://saguaro.ruuster.com/agent/jane-doe/listings/a03c8f61-7e2b-4d95-8a14-6f0b3e9c2d57", "previousPropertyIds": [], "firstSeenAt": "2026-09-10T14:20:51Z", "lastSeenAt": "2026-10-01T06:12:30Z", "mlsModifiedAt": "2026-09-30T16:05:12Z", "updatedAt": "2026-10-01T06:12:30Z" } ] }, "meta": { "brokerageId": "4f6c2a9e-8d31-4b57-9a0e-2c7d5e1b8f43", "range": null, "coverage": { "ownershipAsOf": "2026-10-01T06:12:30Z" }, "total": 47, "nextCursor": "cur_Hk2v9QPq7Lm3XvT8wR" } } ```