# Get the brokerage summary

Source: https://help.ruuster.com/api/summary

```http
GET https://api.ruuster.com/v1/summary
```

The brokerage's numbers by week or month. Each bucket carries weeklyEmail, the exact figures Ruuster's weekly analytics email showed for that week: use those as the headline numbers in anything you show the brokerage or its clients. The measured fields beside them (human opens, signed-in leads) use stricter definitions and are expected to be lower; that is not an error, so don't report it as a discrepancy.

- 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 |
|---|---|---|---|
| `from` | date | 56 days before `to` | First day, `YYYY-MM-DD`, included |
| `to` | date | today | Day after the last day, `YYYY-MM-DD`, excluded |
| `granularity` | string | `week` | `week` or `month` |

## Which numbers to show

Each bucket has two kinds of figures, and they are meant to differ:

- **`weeklyEmail`: the headline.** The figures exactly as Ruuster's weekly (or monthly) analytics email showed them for that period. Your team and clients already see these every week, so use them as the headline numbers in reports, decks and summaries.
- **Everything else in the bucket: the measured detail.** Ruuster's own records, counted more strictly. Use these for breakdowns and trends, labeled for what they are (for example "human opens, excluding automatic opens by mail apps").

The two use different definitions, so the measured figures are lower. Present them as different measures, not as a mismatch:

| Measure | Weekly email (`weeklyEmail`) | Measured (`series`) |
|---|---|---|
| Email open rate | `emailOpenRate`: every recorded open, including automatic opens by mail apps and repeat opens, as the email shows it (can exceed 100) | `emails.openRateHuman`: opens that don't look automated, over emails delivered |
| Email click rate | `emailClickRate`, as the email shows it | `emails.clickRate`: clicks over emails delivered |
| Active people | `uniqueActiveUsers`: everyone the email counts as active | `uniqueActiveLeads`: signed-in leads only |
| Activity | `totalClientActivities`, `totalPageViews` | `clientActivities`, `pageViews.*`: actions and listing views by signed-in leads and agents |
| Emails sent | `searchAlertsSent` | `emails.sent`, `emails.delivered` |

`weeklyEmail` is null for a bucket the email didn't cover (the current week before it's sent, or a brokerage that doesn't receive the email).

## Response

Each bucket in `data.series`:

| Field | Description |
|---|---|
| `weeklyEmail` | The weekly analytics email's figures for this bucket, or null: `totalPageViews`, `totalClientActivities`, `uniqueActiveUsers`, `pageViewsPerUser`, `searchAlertsSent`, `emailOpenRate`, `emailClickRate`, `totalNumberNurturedClients`. The headline numbers; see above |
| `pageViews.public` | Google Analytics page views on your hostnames (all pages) by visitors who weren't logged in |
| `pageViews.lead`, `pageViews.agent` | Listing-page views by signed-in leads and agents, from Ruuster's own records |
| `clientActivities` | Actions by leads on your sites |
| `uniqueActiveLeads` | Distinct leads active in the bucket |
| `pageViewsPerLead` | `pageViews.lead` ÷ `uniqueActiveLeads` |
| `contactAgentClicks`, `tourRequests`, `searches`, `favorites`, `leadsCreated` | Counts |
| `savedSearches.createdByClients`, `createdByAgents` | Saved searches created |
| `emails` | `sent`, `delivered`, `openedHuman`, `openRateHuman`, `clicked`, `clickRate` |

`pageViews.public` covers all pages while `pageViews.lead` and `pageViews.agent` cover listing pages only, so there's no combined total.

`data.platformReported[]` lists the same weekly-email figures as one row per email, keyed by `weekOf` (or `monthOf`), for callers that read them separately. `emailOpenRate` and `emailClickRate` are percentages exactly as the email shows them. It is empty if your brokerage doesn't receive the weekly analytics email.

## Example request

cURL:

```bash
curl -s "https://api.ruuster.com/v1/summary?from=2026-09-21&to=2026-09-28&granularity=week" \
  -H "x-api-key: $RUUSTER_API_KEY" \
  -H "x-email: $RUUSTER_EMAIL"
```

Node.js:

```javascript
const res = await fetch("https://api.ruuster.com/v1/summary?from=2026-09-21&to=2026-09-28&granularity=week", {
  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/summary?from=2026-09-21&to=2026-09-28&granularity=week",
    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": {
    "series": [
      {
        "bucket": "2026-09-21", "partial": false,
        "weeklyEmail": { "totalPageViews": 3611, "totalClientActivities": 4409, "uniqueActiveUsers": 311,
                         "pageViewsPerUser": 12, "searchAlertsSent": 13054, "emailOpenRate": 55, "emailClickRate": 7,
                         "totalNumberNurturedClients": 2210 },
        "pageViews": { "public": 49640, "lead": 2981, "agent": 647 },
        "clientActivities": 4416,
        "uniqueActiveLeads": 312,
        "pageViewsPerLead": 9.6,
        "contactAgentClicks": 21, "tourRequests": 9,
        "savedSearches": { "createdByClients": 14, "createdByAgents": 33 },
        "searches": 1540, "favorites": 97,
        "leadsCreated": 163,
        "emails": { "sent": 13054, "delivered": 13014, "openedHuman": 1433, "openRateHuman": 0.1101, "clicked": 385, "clickRate": 0.0296 }
      }
    ],
    "platformReported": [
      { "weekOf": "2026-09-21", "totalPageViews": 3611, "totalClientActivities": 4409, "uniqueActiveUsers": 311,
        "pageViewsPerUser": 12, "searchAlertsSent": 13054, "emailOpenRate": 55, "emailClickRate": 7,
        "totalNumberNurturedClients": 2210 }
    ]
  },
  "meta": { "range": { "from": "2026-09-21", "to": "2026-09-28", "tz": "America/Chicago" }, "granularity": "week",
            "coverage": { "bucketsRequested": 1, "bucketsCovered": 1, "stableBefore": "2026-09-28" } }
}
```