# List engagement for all listings

Source: https://help.ruuster.com/api/properties-bulk-engagement

```http
GET https://api.ruuster.com/v1/properties/engagement
```

The engagement numbers for all your listings in one paged call, ranked by views, favorites, tour requests or contact requests.

- Authentication: `x-api-key` and `x-email` headers of an owner or admin
- Rate limit: 120 requests per minute per key

Use it instead of one [Get listing engagement](https://help.ruuster.com/api/properties-engagement) call per listing.

## Query parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `from` | date | 30 days before `to` | First day, `YYYY-MM-DD` in America/Chicago, included |
| `to` | date | today | Day after the last day, `YYYY-MM-DD`, excluded |
| `granularity` | string | `week` | `day`, `week` or `month`. With `day`, each listing also carries a `series` |
| `status` | string | `active` | `active`, `pending`, `closed` or `all`, as for List listings |
| `sort` | string | `views` | `views`, `favorites`, `tourRequests` or `contactAgentClicks`, highest first |
| `cursor` | string | | `meta.nextCursor` from the previous page. Omit for the first page |
| `limit` | integer | `100` | Rows per page, 1 to 500 |

## Response

`data.properties` lists your listings with `propertyId`, `mlsRecordId`, `address`, `status` and `totals` for the range, using the fields described on [Get listing engagement](https://help.ruuster.com/api/properties-engagement). With `granularity=day` each item also has a `series`. `meta.total` and `meta.nextCursor` page through all your listings.

## Example request

cURL:

```bash
curl -s "https://api.ruuster.com/v1/properties/engagement?from=2026-09-21&to=2026-09-28&granularity=week&sort=views&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/engagement?from=2026-09-21&to=2026-09-28&granularity=week&sort=views&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/engagement?from=2026-09-21&to=2026-09-28&granularity=week&sort=views&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", "mlsRecordId": "22418765",
        "address": "4182 E Saguaro Bloom Dr, Tucson, AZ 85718", "status": "active",
        "totals": {
          "views": { "total": 3849, "public": { "pageViews": 3776, "users": 1770, "sessions": 1785 }, "loggedIn": { "views": 73, "lead": 64, "agent": 9, "uniqueLeads": 26 } },
          "favorites": 6, "tourRequests": 2, "offers": 0, "shares": { "sent": 4, "opens": 11 }, "contactAgentClicks": 3, "pushAlertsSent": 38
        }
      },
      {
        "propertyId": "a03c8f61-7e2b-4d95-8a14-6f0b3e9c2d57", "mlsRecordId": "22419302",
        "address": "1920 W Mesquite Ridge Ln, Oro Valley, AZ 85737", "status": "active",
        "totals": {
          "views": { "total": 3601, "public": { "pageViews": 3535, "users": 1583, "sessions": 1608 }, "loggedIn": { "views": 66, "lead": 61, "agent": 5, "uniqueLeads": 22 } },
          "favorites": 5, "tourRequests": 1, "offers": 1, "shares": { "sent": 2, "opens": 6 }, "contactAgentClicks": 2, "pushAlertsSent": 41
        }
      }
    ]
  },
  "meta": {
    "range": { "from": "2026-09-21", "to": "2026-09-28", "tz": "America/Chicago" }, "granularity": "week",
    "total": 47,
    "nextCursor": "cur_p8TzQwPq7Lm3XvT8wR"
  }
}
```