Score Gains API

Retrieve leads with the largest recent score increases. Useful for identifying leads that are rapidly gaining engagement and may be ready for outreach.

GET /score-gains

Get leads with the highest score gains for the active Organizational Unit.

Request

Parameter	Type	Required	Description
range	string	No	Time range: today, last_7d, last_30d (default: last_7d)
limit	integer	No	Maximum number of results (default: 10)

Response

200 OK

{
  "leads": [
    {
      "lead_id": "ld_123",
      "score": 85,
      "score_gain": 40,
      "last_event_at": "2025-01-15T10:30:00Z"
    },
    {
      "lead_id": "ld_456",
      "score": 62,
      "score_gain": 28,
      "last_event_at": "2025-01-15T09:15:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
lead_id	string	Lead identifier
score	integer	Current score
score_gain	integer	Score increase in the specified period
last_event_at	timestamp	Most recent event for the lead

Example

curl -X GET "https://api.kenbun.io/score-gains?range=last_7d&limit=10" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
401	Unauthorized	Check authentication token
500	Server Error	Contact support if persists

---

Notes

• Results are OU-scoped to the active Organizational Unit
• Score gains are calculated from score snapshots, so data reflects hourly snapshot resolution
• Leads with no recent activity will not appear in results

Related Endpoints

• Top Leads - Leads ranked by total score
• Score History - Historical score data for a specific lead