# List active leads

Source: https://help.ruuster.com/api/leads-active

```http
GET https://api.ruuster.com/v1/leads/activity
```

Your leads with recorded activity in a period, most active first. The hot list for follow-up.

- 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)

One row per lead with any recorded activity on your sites in the range, ranked by how much they did. Use it to find who to call this week; use [Get a lead's activity](https://help.ruuster.com/api/leads-activity) for one lead's day-by-day detail.

## Query parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `from` | date | 7 days before `to` | First day, `YYYY-MM-DD` in America/Chicago, included |
| `to` | date | today | Day after the last day, `YYYY-MM-DD`, excluded |
| `minActions` | integer | `1` | Only leads with at least this many actions in the range |
| `cursor` | string | | `meta.nextCursor` from the previous page. Omit for the first page |
| `limit` | integer | `100` | Rows per page, 1 to 200 |
| `countOnly` | `0` \| `1` | `0` | `1` returns `{ "total": n }` and no rows |

## Response

`data.leads` is ordered by `totals.actions`, highest first, then by `leadId`. Each row:

| Field | Description |
|---|---|
| `lead` | The short lead form: `leadId`, `firstName`, `lastName`, `email` and `phone` when lead contact details are on, `crmExternalId`, `crmStatus`, `crmTags`, `agentId`, `createdAt`, `lastLoginAt` |
| `totals.actions` | Recorded activities in the range: listing views, searches, favorites, saved-search changes, tour and contact requests, sign-ins and shares |
| `totals.propertyViews`, `favorites`, `savedSearchEvents`, `searches`, `tourRequests`, `contactAgentClicks`, `logins`, `shares` | The breakdown |
| `firstActivityAt`, `lastActivityAt` | First and last recorded activity in the range |

Email opens and clicks aren't part of this ranking; they're on [Get a lead's activity](https://help.ruuster.com/api/leads-activity) and [List a lead's emails](https://help.ruuster.com/api/leads-emails). Rows count against your daily lead-row quota. `meta.coverage` says which days of activity are available; a range that reaches before `coverage.from` ranks on the covered days only.

## Example request

cURL:

```bash
curl -s "https://api.ruuster.com/v1/leads/activity?from=2026-09-28&to=2026-10-01&minActions=10&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/leads/activity?from=2026-09-28&to=2026-10-01&minActions=10&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/leads/activity?from=2026-09-28&to=2026-10-01&minActions=10&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": {
    "leads": [
      {
        "lead": { "leadId": "user:c0ff3e21-8a4b-4c7d-9e15-2b6f8d3a1c04", "firstName": "Sam", "lastName": "Lee",
                  "email": "sam.lee@example.com", "phone": "+15205550142", "crmExternalId": "48213",
                  "crmStatus": "Showing Homes Nurture", "crmTags": ["buyer", "tucson"],
                  "agentId": "7c1e9b42-3d85-4a6f-9e07-1b2c8d4f5a69",
                  "createdAt": "2026-09-21T18:20:05Z", "lastLoginAt": "2026-09-30T02:11:40Z" },
        "totals": { "actions": 41, "propertyViews": 22, "favorites": 3, "savedSearchEvents": 1, "searches": 9,
                    "tourRequests": 1, "contactAgentClicks": 0, "logins": 2, "shares": 1 },
        "firstActivityAt": "2026-09-28T13:02:00Z",
        "lastActivityAt": "2026-09-30T23:58:44Z"
      },
      {
        "lead": { "leadId": "user:4a9e2c71-0b58-4d3f-8e26-5c1d7b9f3a40", "firstName": "Dana", "lastName": "Okafor",
                  "email": "dana.okafor@example.com", "phone": "+15205550166", "crmExternalId": "50322",
                  "crmStatus": "Active", "crmTags": ["buyer"],
                  "agentId": "e5a7d3c1-9b46-4f28-8c0e-6d2a1f7b3e95",
                  "createdAt": "2026-08-30T15:12:41Z", "lastLoginAt": "2026-09-30T22:48:03Z" },
        "totals": { "actions": 17, "propertyViews": 11, "favorites": 1, "savedSearchEvents": 0, "searches": 4,
                    "tourRequests": 0, "contactAgentClicks": 0, "logins": 1, "shares": 0 },
        "firstActivityAt": "2026-09-29T01:40:17Z",
        "lastActivityAt": "2026-09-30T23:05:51Z"
      }
    ]
  },
  "meta": {
    "range": { "from": "2026-09-28", "to": "2026-10-01", "tz": "America/Chicago" },
    "coverage": { "from": "2026-07-03", "to": "2026-10-01", "stableBefore": "2026-09-29" },
    "nextCursor": "cur_k3Vb8ePq7Lm3XvT8wR"
  }
}
```