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 analytics for a GrowSurf participant by ID or email to view engagement, rank, revenue, and activation milestones.

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

TableJSON 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`	No	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

TableJSON 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.

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.3/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds non-obvious behavior: a null milestone with partial `state` means unknown rather than never-happened, the API returns 400 for unknown `include` values, and date params deliberately do not filter the base response or activation milestones. It stops short of auth or rate-limit context, but the added semantics are substantive.

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-loaded with the base response contents, then include options, then filtering rules, then campaign targeting — a logical progression. It is dense and repeats the date-window constraint already in the schema, but nearly every sentence carries operational weight.

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

Completeness4/5

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

Given an output schema exists, the description needn't explain return shapes, and it correctly focuses on include semantics, filter scoping, and targeting. The anyOf participantId/participantEmail requirement is only implied ('by ID or email') rather than stated as a mutual requirement, a minor gap.

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?

With 75% schema coverage the schema documents most params, but the description adds real meaning: the 1825-day cap and ordering constraint, that date filters scope only optional series/email data, and that `campaignId` falls back to GROWSURF_CAMPAIGN_ID. It goes beyond restating the schema, though it repeats some schema text.

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 and resource ('Fetch analytics for one participant') and pins the lookup key ('by GrowSurf participant ID or email'). The 'one participant' scope implicitly separates it from sibling campaign-level analytics tools like growsurf_get_campaign_analytics and growsurf_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 concrete operational guidance: add `activation` for the eligibility anchor, request both `activation` and `series` for covered buckets, and filter with `days`/`startDate`/`endDate`. However, it never names alternative sibling tools (e.g. participant activity logs vs. campaign analytics) or states when this tool should be chosen over them.

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

Deploy Server