Analytics API

The analytics router provides reporting and analysis over scored data -- tier distributions, score timelines, top accounts, conversion attribution, and engagement cadence patterns.

Router namespace: analytics

Source: src/server/trpc/routers/analytics.ts

Procedures

Procedure	Type	Access	Description
getDistribution	query	tenant	Tier distribution counts by entity type
getScoreHistory	query	tenant	Score timeline for a single entity
getTopAccounts	query	tenant	Top accounts ranked by combined score
snapshotScores	mutation	admin	Snapshot current engagement scores to history
getConversionAttribution	query	admin	Signal-to-conversion correlation analysis
getPipelineCorrelation	query	admin	Score tier vs conversion rate analysis
getAccountCadences	query	tenant	Engagement cadence patterns across accounts

---

getDistribution

Returns the count of entities in each score tier for a given entity type.

analytics.getDistribution.queryOptions(input)

Input

Field	Type	Required	Description
entityType	"person" | "account" | "opportunity"	Yes	Entity type to analyze

Response

{
  "entityType": "account",
  "distribution": {
    "hot": 24,
    "warm": 87,
    "cool": 156,
    "cold": 73
  },
  "total": 340
}

Example

const trpc = useTRPC();
const { data } = useQuery(
  trpc.analytics.getDistribution.queryOptions({ entityType: "account" })
);

---

getScoreHistory

Returns the score timeline for a single entity over a configurable number of days. Used for trend charts on entity detail pages.

analytics.getScoreHistory.queryOptions(input)

Input

Field	Type	Required	Default	Description
entityId	string	Yes	--	Entity identifier
days	number (1-365)	No	30	Number of days of history

Response

[
  {
    "date": "2026-03-05",
    "fitScore": 82.5,
    "engagementScore": 67.3,
    "combinedScore": 74.9,
    "tier": "warm"
  },
  {
    "date": "2026-03-04",
    "fitScore": 82.5,
    "engagementScore": 71.0,
    "combinedScore": 76.8,
    "tier": "warm"
  }
]

---

getTopAccounts

Returns the highest-scoring accounts ranked by combined score.

analytics.getTopAccounts.queryOptions(input)

Input

Field	Type	Required	Default	Description
limit	number (1-100)	No	10	Number of accounts to return

Response

[
  {
    "accountId": "acc_456",
    "accountName": "Acme Corporation",
    "fitScore": 92.0,
    "engagementScore": 88.5,
    "combinedScore": 90.3,
    "tier": "hot"
  }
]

---

snapshotScores

Captures the current engagement scores for all entities and writes them to the score history table. This is typically called automatically after scoring runs but can be triggered manually.

analytics.snapshotScores.mutationOptions(options)

Access: Admin only

Input

None.

Response

{
  "snapshotId": "snap_abc123",
  "entityCount": 1679,
  "snapshotAt": "2026-03-05T10:30:00.000Z"
}

---

getConversionAttribution

Analyzes which engagement signals correlate most strongly with closed-won conversions over a given time period.

analytics.getConversionAttribution.queryOptions(input)

Access: Admin only

Input

Field	Type	Required	Default	Description
days	number (1-365)	No	90	Lookback window in days

Response

[
  {
    "signal": "meeting_attended",
    "conversionRate": 0.42,
    "sampleSize": 156,
    "correlation": 0.68
  },
  {
    "signal": "email_replied",
    "conversionRate": 0.31,
    "sampleSize": 423,
    "correlation": 0.52
  }
]

info

Attribution data requires sufficient closed-won deal volume. Results are unreliable with fewer than 30 closed-won deals in the lookback window.

---

getPipelineCorrelation

Compares conversion rates across score tiers to validate that scoring correlates with actual pipeline outcomes.

analytics.getPipelineCorrelation.queryOptions()

Access: Admin only

Input

None.

Response

[
  { "tier": "hot", "conversionRate": 0.38, "avgDealSize": 125000, "count": 24 },
  { "tier": "warm", "conversionRate": 0.18, "avgDealSize": 82000, "count": 87 },
  { "tier": "cool", "conversionRate": 0.07, "avgDealSize": 45000, "count": 156 },
  { "tier": "cold", "conversionRate": 0.02, "avgDealSize": 31000, "count": 73 }
]

---

getAccountCadences

Analyzes engagement cadence patterns across accounts -- how frequently accounts engage and whether cadence is accelerating or decelerating.

analytics.getAccountCadences.queryOptions(input)

Input

Field	Type	Required	Default	Description
window	number (1-180)	No	30	Analysis window in days

Response

[
  {
    "accountId": "acc_456",
    "accountName": "Acme Corporation",
    "avgDaysBetweenActivities": 2.3,
    "cadenceTrend": "accelerating",
    "activityCount": 18,
    "tier": "hot"
  },
  {
    "accountId": "acc_789",
    "accountName": "Globex Inc",
    "avgDaysBetweenActivities": 8.7,
    "cadenceTrend": "decelerating",
    "activityCount": 5,
    "tier": "cool"
  }
]

Cadence Trend	Description
accelerating	Activities becoming more frequent
stable	Consistent engagement rhythm
decelerating	Activities becoming less frequent
sporadic	No consistent pattern

Related Pages

• Scoring API -- Scoring execution that generates the data analyzed here
• Propensity API -- ML predictions that complement analytics
• tRPC Overview -- Client setup and procedure types