GrowSurf MCP Server

Official

by growsurf

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Get Participant Analytics

growsurf_get_participant_analytics

Read-onlyIdempotent

Fetch all-time engagement, rank, share, affiliate revenue, commission, and payout analytics for one GrowSurf participant by ID or email, with optional activation, series, and email data.

Instructions

Fetch analytics for one participant by GrowSurf participant ID or email. The base response includes all-time engagement, rank, share, and applicable affiliate revenue, commission, and payout metrics. Add activation to include for the program-specific eligibility anchor and covered first milestones, including firstPortalViewedAt and firstShareChannel. A null milestone with a partial or unavailable state is unknown, not proof that the action never happened. Request both activation and series for covered portalViews and shareActions buckets. Filter optional series and email data with days (up to 1825) or both startDate and endDate as positive Unix timestamps in milliseconds. endDate must be at or after startDate, and the range can span at most 1825 days. These date parameters do not filter the base response or activation milestones. Targets campaignId if passed, otherwise GROWSURF_CAMPAIGN_ID.

Input Schema

Name	Required	Description
`days`	No	Number of days for optional `series` and `email` analytics. Does not filter the all-time base response.
`endDate`	No	End of the optional-data timeframe, positive Unix timestamp in milliseconds. Supply `startDate` too; `endDate` must be >= `startDate` and at most 1825 days later.
`include`	No	Comma-separated optional data. Current values are `series`, `email`, and `activation`; the API returns `400` for unknown values.
`interval`	No	Bucket size for `series` and email series. Defaults to `day`.
`startDate`	No	Start of the optional-data timeframe, positive Unix timestamp in milliseconds. Supply `endDate` too; the window must span at most 1825 days.
`campaignId`	Yes	Target program (campaign) id for this call. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Program IDs also identify newly created programs without restarting the server.
`participantId`	No
`participantEmail`	No

Output Schema

Name	Required	Description
`email`	No	Sent, delivered, opened, clicked, bounced, and spam complaint metrics for program emails in the requested window.
`ranks`	No	Leaderboard ranks for this participant.
`series`	No	This participant's per-period activity. Present when `include` contains `series`.
`endDate`	No	Window end (Unix ms). Present with `series` or `email`.
`analytics`	No	All-time participant analytics totals. Date-window parameters do not filter these fields.
`startDate`	No	Window start (Unix ms). Present with `series` or `email`.
`activation`	No	Opt-in covered eligibility and first-milestone analytics for one participant.
`shareCount`	No	Per-channel share counts (e.g. `email`, `facebook`, `twitter`).

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.19.15Oct 15, 2026
- addedInput schema / properties / campaignId / minLength
```
Added value: +1
```
- addedInput schema / required
```
Added value: +[
+  "campaignId"
+]
```

Changed1 schema field changedv0.19.9Oct 3, 2026

changedInput schema / properties / campaignId / description

Previous value: -"Target program (campaign) id for this call. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Pass the `id` returned by growsurf_create_campaign to configure or operate a program you just created, without restarting the server."New value: +"Target program (campaign) id for this call. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Program IDs also identify newly created programs without restarting the server."

Changed5 schema fields changedv0.19.8Oct 1, 2026

addedInput schema / allOf

Added value: +[
+  {
+    "if": {
+      "required": [
+        "startDate"
+      ]
+    },
+    "then": {
+      "required": [
+        "endDate"
+      ]
+    }
+  },
+  {
+    "if": {
+      "required": [
+        "endDate"
+      ]
+    },
+    "then": {
+      "required": [
+        "startDate"
+      ]
+    }
+  }
+]

changedInput schema / properties / endDate / description

Previous value: -"End of the optional-data timeframe, Unix timestamp in ms. Use with `startDate`."New value: +"End of the optional-data timeframe, positive Unix timestamp in milliseconds. Supply `startDate` too; `endDate` must be >= `startDate` and at most 1825 days later."

addedInput schema / properties / endDate / minimum
```
Added value: +1
```

changedInput schema / properties / startDate / description

Previous value: -"Start of the optional-data timeframe, Unix timestamp in ms. Use with `endDate` instead of `days`."New value: +"Start of the optional-data timeframe, positive Unix timestamp in milliseconds. Supply `endDate` too; the window must span at most 1825 days."

addedInput schema / properties / startDate / minimum
```
Added value: +1
```

Changed9 schema fields changedv0.14.0Sep 10, 2026

addedInput schema / properties / days / description

Added value: +"Number of days for optional `series` and `email` analytics. Does not filter the all-time base response."

changedInput schema / properties / endDate / description

Previous value: -"End of the timeframe, Unix timestamp in ms."New value: +"End of the optional-data timeframe, Unix timestamp in ms. Use with `startDate`."

changedInput schema / properties / include / description

Previous value: -"Comma-separated optional data. Current values are `series` and `email`; the API returns `400` for unknown values."New value: +"Comma-separated optional data. Current values are `series`, `email`, and `activation`; the API returns `400` for unknown values."

changedInput schema / properties / startDate / description

Previous value: -"Start of the timeframe, Unix timestamp in ms. Use with endDate instead of days."New value: +"Start of the optional-data timeframe, Unix timestamp in ms. Use with `endDate` instead of `days`."

addedOutput schema / properties / activation

Added value: +{
+  "description": "Opt-in covered eligibility and first-milestone analytics for one participant.",
+  "properties": {
+    "cohort": {
+      "description": "Program-specific eligibility anchor and covered value.",
+      "properties": {
+        "anchorAt": {
+          "description": "Covered anchor time (Unix ms). `null` is unknown and does not mean enrollment never occurred.",
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "anchorField": {
+          "enum": [
+            "enrolledAsAdvocateAt",
+            "approvedAsAffiliateAt"
+          ],
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "coverageStartAt": {
+      "description": "Earliest expected complete participant activation capture time (Unix ms).",
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "enrolledAsAdvocateAt": {
+      "description": "Referral only. Covered advocate enrollment (Unix ms); `null` does not mean enrollment never occurred.",
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "metricContractVersion": {
+      "description": "Shared activation and engagement metric version.",
+      "type": "integer"
+    },
+    "milestones": {
+      "description": "Covered first milestones. A `null` value is unknown and does not mean the action never happened.",
+      "properties": {
+        "firstCommissionAt": {
+          "description": "Affiliate only. First covered commission (Unix ms).",
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "firstLeadAt": {
+          "description": "First covered referred lead (Unix ms).",
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "firstPortalViewedAt": {
+          "description": "First covered signed-in portal view (Unix ms).",
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "firstReferralAt": {
+          "description": "First covered credited referral (Unix ms).",
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "firstReferralLinkCopiedAt": {
+          "description": "First covered referral-link copy (Unix ms).",
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "firstRewardAt": {
+          "description": "Referral only. First covered participant reward (Unix ms).",
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "firstShareAt": {
+          "description": "First covered accepted share action (Unix ms).",
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "firstShareChannel": {
+          "description": "Channel for `firstShareAt`, or `null` when the first covered share is unavailable.",
+          "enum": [
+            "email",
+            "facebook",
+            "twitter",
+            "linkedin",
+            "pinterest",
+            "threads",
+            "bluesky",
+            "sms",
+            "messenger",
+            "whatsapp",
+            "wechat",
+            "telegram",
+            "reddit",
+            "tumblr",
+            "qrcode",
+            "copyRefLink",
+            "iosNativeShare",
+            "androidNativeShare",
+            null
+          ],
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "firstUniqueClickAt": {
+          "description": "First covered unique referral visit (Unix ms).",
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "payoutSetupCompletedAt": {
+          "description": "First covered payout-setup completion (Unix ms).",
+          "type": [
+            "integer",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "programType": {
+      "description": "Program eligibility model.",
+      "enum": [
+        "REFERRAL",
+        "AFFILIATE"
+      ],
+      "type": "string"
+    },
+    "reason": {
+      "description": "Why a value is partial or unavailable, or `null` when it is available.",
+      "enum": [
+        "COVERAGE_UNAVAILABLE",
+        "PRE_COVERAGE",
+        "PARTIAL_COVERAGE",
+        "INSUFFICIENT_COVERAGE",
+        "EMPTY_DENOMINATOR",
+        "QUERY_LIMIT_EXCEEDED",
+        "PARTICIPANT_NOT_ELIGIBLE",
+        null
+      ],
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "state": {
+      "description": "Whether the value is complete, partial, or unavailable for the requested bounds.",
+      "enum": [
+        "AVAILABLE",
+        "PARTIAL",
+        "UNAVAILABLE"
+      ],
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

changedOutput schema / properties / analytics / description

Previous value: -"Participant analytics totals."New value: +"All-time participant analytics totals. Date-window parameters do not filter these fields."

changedOutput schema / properties / analytics / properties / leads / description

Previous value: -"Pending referral credits."New value: +"Current pending referral credits."

addedOutput schema / properties / series / items / properties / portalViews

Added value: +{
+  "description": "Covered signed-in portal views, or `null` outside known coverage.",
+  "type": [
+    "integer",
+    "null"
+  ]
+}

addedOutput schema / properties / series / items / properties / shareActions

Added value: +{
+  "description": "Covered accepted share actions, or `null` outside known coverage.",
+  "type": [
+    "integer",
+    "null"
+  ]
+}

First observedv0.12.2Aug 25, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare a safe read (readOnly, idempotent, non-destructive, closed-world), yet the description adds substantial behavior: what the base response contains, what `activation` unlocks, the 1825-day cap, and the crucial null-milestone interpretation rule. It also warns that date params do not filter the base response or milestones.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose and then layers optional behavior; nearly every sentence carries non-obvious rules. It is dense and slightly long, but no sentence is pure filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite 8 parameters and conditional (anyOf/allOf) schema constraints, the description covers the base vs optional response split, include semantics, date-window rules, and the null-milestone caveat. With an output schema present, no return-format explanation is needed, so nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%, so the schema already documents most parameters. The description still adds integration-level meaning: that date params do not filter the base response, that `endDate` must be >= `startDate` within 1825 days, and the campaignId targeting fallback to GROWSURF_CAMPAIGN_ID.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Fetch) and resource (analytics for one participant) plus the two identification keys (participant ID or email). The 'one participant' scoping cleanly distinguishes it from the campaign-level siblings like get_campaign_analytics and get_campaign_activation_analytics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit conditional guidance: add `activation` for eligibility/milestones, request both `activation` and `series` for covered buckets, and how to bound ranges with `days` or `startDate`/`endDate`. It lacks explicit routing against adjacent siblings (get_participant, get_participant_activity_logs), so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server