Your CRM

Count engaged leads by CRM pond, stage, agent or tag

GEThttps://api.ruuster.com/v1/leads/crm-segments

How many of your leads engaged on your Ruuster sites in a period, counted by where they sit in your CRM (pond, stage, assigned agent or tag), optionally filtered to some ponds or stages and with the leads listed. Answers "how many leads in our inactive ponds engaged meaningfully?" in one call.

Authentication: x-api-key and x-email headers of an owner or admin
Rate limit: lookup call, 20 per minute per key, within the 120 per minute
Your CRM: x-crm-vendor and x-crm-key headers with your CRM's API key, used for this request only. See Connect your CRM
Rows count against the daily lead-row quota (50,000 by default)

View as Markdown

Ruuster activity counted by your CRM's own segments. Ruuster takes every lead engaged at the engagement level in the range, looks each one up in your CRM by the CRM id Ruuster's CRM sync stored on the lead (crmExternalId), and counts them by groupBy. Filter to some ponds, stages, tags or one agent, and add list=1 for the leads themselves.

Typical questions: "how many leads in our inactive ponds have engaged meaningfully with Ruuster this month?" (groupBy=pond&pond=inactive), "which stages are our most engaged leads in?" (groupBy=stage&engagement=strong), "which agents' leads are most active?" (groupBy=agent).

This call reads your CRM live with your CRM's API key (headers x-crm-vendor and x-crm-key; used for this request only, never stored), with that key's own permissions. Follow Up Boss supports every grouping. Sierra and Sure Send can't look many people up at once, so for them groupBy=stage and groupBy=tag count from the copy of each lead's CRM stage and tags that Ruuster's CRM sync keeps (no CRM call), and ponds and agents answer 400 crm_not_supported. See Connect your CRM.

Query parameters

Name	Type	Default	Description
`from`	date	30 days before `to`	First day of Ruuster activity, `YYYY-MM-DD` in America/Chicago, included. At most 93 days
`to`	date	tomorrow	Day after the last day, `YYYY-MM-DD`, excluded. The default includes today
`engagement`	`any` \| `viewed` \| `meaningful` \| `strong`	`meaningful`	Who counts as engaged on Ruuster: `meaningful` 3 or more listing views, or any favorite, tour request, contact-agent click or share; `strong` a tour request or contact-agent click, 10 or more views, or 2 or more favorites; `viewed` viewed at least one listing; `any` any recorded activity
`groupBy`	`pond` \| `stage` \| `agent` \| `tag`	`pond`	What to count by. A lead counts once per tag it carries
`pond`	string		Only people in these ponds: a pond id, or a name to match (comma-separate several), e.g. `inactive` matches every pond whose name contains it
`stage`	string		Only people in this CRM stage (comma-separate several)
`tag`	string		Only people carrying this CRM tag (comma-separate several; any of them)
`assignedUserId`	string		Only people assigned to this CRM user (an id from Get your CRM's vocabulary)
`list`	`0` \| `1`	`0`	`1` also returns the matching leads, most engaged first
`limit`	integer	`50`	With `list=1`, most leads returned, 1 to 500

Response

Field	Description
`segments[]`	One row per pond, stage, agent or tag, largest first: `key`, `name`, `leads`, and how many of them were `strong`, `meaningful` and `viewed`, their `propertyViews` and the latest `lastActivityAt`. People in no pond, with no stage or tag, or unassigned have their own row (`key` `none`)
`totals`	`engagedOnRuuster`, `linkedToCrm`, `checkedInCrm`, `foundInCrm`, `notFoundInCrm`, `matchingFilters` (the leads counted)
`criteria`	The rules in words, and with `pond` the ponds it matched
`ponds`	Every pond in the account (with `groupBy=pond` or a `pond` filter)
`leads`	With `list=1`: rows like Find engaged leads your CRM hasn't called

meta.crm names the CRM and its source (live, or Ruuster's synced copy), the number of CRM calls made, and any caution. Up to the 2,000 most engaged leads linked to your CRM are looked up per call.

Request

curl -s "https://api.ruuster.com/v1/leads/crm-segments?engagement=meaningful&groupBy=pond&pond=inactive" \
  -H "x-api-key: $RUUSTER_API_KEY" \
  -H "x-email: $RUUSTER_EMAIL" \
  -H "x-crm-vendor: fub" \
  -H "x-crm-key: $CRM_API_KEY"

const res = await fetch("https://api.ruuster.com/v1/leads/crm-segments?engagement=meaningful&groupBy=pond&pond=inactive", {
  headers: {
    "x-api-key": process.env.RUUSTER_API_KEY,
    "x-email": process.env.RUUSTER_EMAIL,
    "x-crm-vendor": "fub",
    "x-crm-key": process.env.CRM_API_KEY,
  },
});
const body = await res.json();
if (!body.ok) throw new Error(`${body.error.code}: ${body.error.message} (${body.requestId})`);
console.log(body.data);

import os
import requests

res = requests.get(
    "https://api.ruuster.com/v1/leads/crm-segments?engagement=meaningful&groupBy=pond&pond=inactive",
    headers={"x-api-key": os.environ["RUUSTER_API_KEY"], "x-email": os.environ["RUUSTER_EMAIL"], "x-crm-vendor": "fub", "x-crm-key": os.environ["CRM_API_KEY"]},
    timeout=30,
)
body = res.json()
if not body["ok"]:
    raise RuntimeError(f'{body["error"]["code"]}: {body["error"]["message"]} ({body.get("requestId")})')
print(body["data"])

{ "ok": true, "data": { "segments": [ { "key": "4", "name": "Inactive Buyers", "leads": 57, "strong": 9, "meaningful": 57, "viewed": 55, "propertyViews": 1183, "lastActivityAt": "2026-10-21T22:40:12Z" }, { "key": "9", "name": "Inactive - Sellers", "leads": 11, "strong": 1, "meaningful": 11, "viewed": 10, "propertyViews": 142, "lastActivityAt": "2026-10-20T15:02:33Z" } ], "totals": { "engagedOnRuuster": 406, "linkedToCrm": 351, "checkedInCrm": 351, "foundInCrm": 333, "notFoundInCrm": 18, "matchingFilters": 68 }, "criteria": { "engagement": "meaningful", "engagementRule": "3 or more listing views, or any favorite, tour request, contact-agent click or share", "groupBy": "pond", "pond": "inactive", "ponds": [ { "id": "4", "name": "Inactive Buyers" }, { "id": "9", "name": "Inactive - Sellers" } ] }, "ponds": [ { "id": "2", "name": "New Leads" }, { "id": "4", "name": "Inactive Buyers" }, { "id": "9", "name": "Inactive - Sellers" } ] }, "meta": { "range": { "from": "2026-09-22", "to": "2026-10-22", "tz": "America/Chicago" }, "coverage": { "from": "2026-07-03", "to": "2026-10-22", "stableBefore": "2026-10-20" }, "crm": { "vendor": "fub", "label": "Follow Up Boss", "source": "Follow Up Boss, live, with your API key", "calls": 5, "note": "A lead counts once per pond." } } }