# Get your account's highlights

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

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

Highlights for the brokerage in one call. Figures that grew against the previous period of the same length, the most-viewed listings, the most engaged leads, agent activity, the hottest areas with Ruuster's share of listing views, and, for Follow Up Boss accounts, dormant leads re-engaged after a Ruuster touch. Highlights only; for every figure, including those that fell, use summary.

- Authentication: `x-api-key` and `x-email` headers of an owner or admin
- Rate limit: 120 requests per minute per key
- Rows count against the daily lead-row quota (50,000 by default)

What is going well on your account, gathered from the other endpoints and put in plain sentences. Use it for a "what has Ruuster done for us" recap, a renewal or QBR slide, or a team shout-out.

**This endpoint reports highlights, not a full picture.** A figure is shown three ways:

- **Grew**: it rose against the previous period of the same length, and both periods are covered by Ruuster's records. The figure comes with `previous` and `growthPct`; a `growthPct` of null means up from zero.
- **Volume**: it is above zero but didn't grow, or the earlier period isn't covered. Only `value` is given, with no comparison.
- **Left out**: it is zero or unknown.

So a figure that fell appears without a comparison, and `/wins` never states a decline. For the complete numbers, ups and downs alike, use [Get the brokerage summary](https://help.ruuster.com/api/summary).

What the sections are based on:

- **Engagement** comes from the same records as `/summary`. `engagedLeads` counts the distinct leads active on Ruuster in the period. `nurturedClients` is the figure from Ruuster's weekly analytics email. New leads and sign-ups are not included: Ruuster mostly works existing and cold leads, so engagement is the measure, and lead counts include contacts imported from your CRM.
- **Top listings** are your own listings, ranked by views as in [Rank your listings' engagement](https://help.ruuster.com/api/properties-bulk-engagement).
- **Top leads** are the most active leads, as in [List active leads](https://help.ruuster.com/api/leads-active).
- **Agents** counts the people on your account, the agents added in the period, and agents' own activity.
- **Markets** is the [leads map](https://help.ruuster.com/api/leads-map) for the last 30 days with `sources=1`. It covers listing views on Ruuster and listing views your CRM recorded from other sources (portals, IDX sites). An area counts as led by Ruuster when more than half of its views were on Ruuster, and the share is given only for those areas. It is never over 30 days, whatever range you ask for, because listing activity is kept for 30 days.
- **Wake-ups** are for Follow Up Boss accounts only:
  - A lead counts as woken when it had no activity on either side (calls, texts, appointments, deals, Ruuster) for at least `minDarkDays` before a Ruuster touch.
  - A meeting counts when it was booked after a Ruuster touch.
  - This is the same data as Ruuster Impact. It shows that a touch came before a meeting, not that the touch caused it.
  - `verified` stories passed the stricter check that Ruuster's published wake-up stories use.
  - History starts at `historyFrom` and runs through `historyThrough`. When that is earlier than the end of your range, the wake-up figures stop there.
  - No deal, contract or sale figures are included.

## Query parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `from` | date | 28 days before `to` | First day, `YYYY-MM-DD` in America/Chicago, included. With neither date, the last 4 complete weeks (Monday to Monday) |
| `to` | date | the start of this week | Day after the last day, `YYYY-MM-DD`, excluded. At most 182 days after `from` |
| `minDarkDays` | `30` \| `90` \| `180` \| `365` | `90` | How long a lead must have been quiet to count as woken up |
| `agent` | string | your default agent | Whose page the `topListings` 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

| Field | Description |
|---|---|
| `headlines` | Up to 6 sentences, strongest first, written from the figures below |
| `engagement` | `engagedLeads` (distinct leads active on Ruuster), `nurturedClients`, `listingViews`, `clientActivities`, `favorites`, `savedSearches`, `tourRequests`, `contactAgentClicks`, `searches`, `emailOpens` (human opens), `emailClicks`: each `{ value, previous?, growthPct? }` |
| `records` | Weeks that beat every other complete week in the two periods: `metric`, `week` (its Monday), `value`, `weeksCompared` |
| `topListings` | Up to 5 of your listings: `propertyId`, `address`, `mlsRecordId`, `url`, `views` (signed-in and public), `uniqueLeads`, `favorites`, `tourRequests` |
| `topLeads` | Up to 5 leads: `lead` (`leadId`, `firstName`, `lastName`, `email`, `phone`, `crmExternalId`, `crmStatus`, `agentId`), `actions`, `propertyViews`, `favorites`, `tourRequests`, `lastActivityAt` |
| `agents` | `activeAgents` (people on your account), `newAgents` (added in the period), `agentPageViews`, `agentSavedSearches` (saved searches agents set up for clients) |
| `markets` | `range`, `ruusterLedAreas`, `topAreas` (up to 5: `city`, `state`, `leads`, `views`, `favorites`, and `ruusterShare` with `ruusterLed: true` where Ruuster leads), and `map`: the [leads map](https://help.ruuster.com/api/leads-map) response with `groupBy=listing` and `sources=1`, so every property is its own point (up to 600 of yours, plus other-source points) |
| `wakeups` | `leadsTouched`, `leadsWoken`, `longestDarkDays`, `wokenWhoBooked`, `meetingsAfterRuuster`, `meetingsRuusterLastTouch`, `verifiedWakeups`, `historyFrom`, `historyThrough`, and `stories` (up to 5: `leadId` when the lead is on Ruuster, `name`, `darkDays`, `wokeAt`, `wokeBy`, `meetingBookedAt`, `verified`) |

A section with nothing to show is left out. `meta.comparedWith` is the earlier period. `meta.unavailable` names any section that couldn't be read just then; try again later for it. Names follow your lead-contact-details setting: with it off, a story's `name` is shortened to "Karin M.". Leads in `topLeads` and `wakeups.stories` count against the daily lead-row quota.

## Example request

cURL:

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

Node.js:

```javascript
const res = await fetch("https://api.ruuster.com/v1/wins?from=2026-09-21&to=2026-10-19", {
  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/wins?from=2026-09-21&to=2026-10-19",
    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": {
    "headlines": [
      "Leads engaged on Ruuster up 23% to 1,412",
      "Listing views up 21% to 18,230",
      "Ruuster woke up 38 leads who had gone quiet for 3 months or more (one after 2.4 years)",
      "41 meetings booked after a Ruuster touch",
      "Ruuster drives most of the listing views in 7 of your top 10 areas, led by Roswell, GA"
    ],
    "engagement": {
      "engagedLeads": { "value": 1412, "previous": 1148, "growthPct": 23 },
      "listingViews": { "value": 18230, "previous": 15102, "growthPct": 21 },
      "tourRequests": { "value": 14, "previous": 0, "growthPct": null }
    },
    "topListings": [
      { "propertyId": "6f1c2b9e-3d4a-4f6b-9a7e-1c2d3e4f5a6b", "address": "123 Main St, Roswell, GA 30075",
        "mlsRecordId": "7351234", "url": "https://homes.example.com/listings/6f1c2b9e-3d4a-4f6b-9a7e-1c2d3e4f5a6b",
        "views": 842, "uniqueLeads": 97, "favorites": 12 }
    ],
    "agents": { "activeAgents": { "value": 42 }, "newAgents": { "value": 3 } },
    "markets": {
      "range": { "from": "2026-09-19", "to": "2026-10-19", "tz": "America/Chicago" },
      "ruusterLedAreas": 7,
      "topAreas": [ { "city": "Roswell", "state": "GA", "leads": 38, "views": 112, "ruusterShare": 0.81, "ruusterLed": true } ]
    },
    "wakeups": {
      "leadsTouched": 512, "leadsWoken": 38, "longestDarkDays": 876, "meetingsAfterRuuster": 41,
      "historyFrom": "2026-02-01", "historyThrough": "2026-10-18",
      "stories": [ { "leadId": "user:0b5e8f6a-1c2d-4e3f-8a9b-0c1d2e3f4a5b", "name": "Karin Morten", "darkDays": 876,
                     "wokeAt": "2026-10-02T14:11:00.000Z", "wokeBy": "click", "meetingBookedAt": "2026-10-03T16:40:00.000Z", "verified": true } ]
    }
  },
  "meta": {
    "range": { "from": "2026-09-21", "to": "2026-10-19", "tz": "America/Chicago" },
    "comparedWith": { "from": "2026-08-24", "to": "2026-09-21" },
    "minDarkDays": 90
  }
}
```