GrowSurf MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

growsurf_get_participant_analytics

Read-onlyIdempotent

Fetch analytics for a single GrowSurf participant by ID or email, including engagement, rank, share, and affiliate revenue. Optionally include activation milestones and time-series 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. Date-window parameters filter optional series and email data, not 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, Unix timestamp in ms. Use with `startDate`.
`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, Unix timestamp in ms. Use with `endDate` instead of `days`.
`campaignId`	No	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.
`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.

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

Behavior5/5

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

Annotations already mark read-only/idempotent/non-destructive, and the description adds rich behavioral detail: date windows only affect optional series/email data, null milestones with partial state are unknown rather than proof of non-occurrence, and campaignId fallback. No contradiction.

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

Conciseness5/5

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

The description is dense but every sentence carries distinct semantic value, starting with the core purpose and then layering optional behavior, edge-case semantics, and scoping rules. No filler or redundancy.

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?

For a parameter-rich analytics call, the description covers identification methods, optional data selection, date filtering scope, default campaign targeting, and null-state interpretation. The output schema exists, so return value details are not required.

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

Parameters5/5

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

The description adds substantial meaning beyond the schema: it defines include values (activation, series, email), explains activation milestone semantics, and clarifies that date-window parameters do not filter the base response. This compensates for the 75% schema coverage and clarifies the most subtle parameters.

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?

Description opens with a specific verb and resource: 'Fetch analytics for one participant by GrowSurf participant ID or email.' It clearly delimits scope (one participant) and names the response contents, making it distinguishable from campaign-level analytics siblings.

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?

Clear context is provided: the tool is for per-participant analytics, with optional include values and campaign targeting behavior. It doesn't explicitly name alternatives or say when not to use it, but the one-participant scope and optional-data guidance are sufficient in context.

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

Deploy Server