Substack MCP Server

get_post_analytics

Read-only

Retrieve performance stats for a published post by ID, including views, email opens, signups, subscribes, estimated value, comments, and reactions. Use it to gauge post impact without writing data.

Instructions

Get performance stats (views, emails sent/delivered/opened, signups, subscribes, estimated value, comments, reactions) for a published post by ID. First reads the exact post detail (one authenticated read) and requires a published post with a post date. A draft, 403/404, malformed detail, ID mismatch, or other detail error except 401/429 triggers a scan of at most the 500 most recent published posts with up to 10 more reads. No writes. A feed-scan miss is bounded, not proof the post never existed; separate pages can shift. stats_available is false when a found post has no statistics. Per-post rates are upstream 0–1 fractions and are not added to this legacy projection.

Input Schema

Name	Required	Description	Default
`post_id`	Yes	The published post ID to get stats for

Output Schema

Name	Required	Description	Default
`id`	No
`note`	No
`sent`	No
`found`	Yes
`title`	No
`views`	No
`opened`	No
`source`	No
`post_id`	No
`scanned`	No
`signups`	No
`delivered`	No
`post_date`	No
`subscribes`	No
`feed_capped`	No
`comment_count`	No
`search_result`	No
`reaction_count`	No
`estimated_value`	No
`stats_available`	No
`detail_fallback_reason`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.3.0Sep 24, 2026

addedOutput schema / properties / detail_fallback_reason

Added value: +{
+  "enum": [
+    "not_found",
+    "malformed",
+    "id_mismatch",
+    "forbidden",
+    "not_published",
+    "upstream_error"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / source

Added value: +{
+  "enum": [
+    "post_detail",
+    "published_feed_scan"
+  ],
+  "type": "string"
+}

Changed4 schema fields changedv1.2.0Sep 15, 2026

addedOutput schema / properties / feed_capped

Added value: +{
+  "type": [
+    "boolean",
+    "null"
+  ]
+}

addedOutput schema / properties / scanned

Added value: +{
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

addedOutput schema / properties / search_result

Added value: +{
+  "enum": [
+    "archive_exhausted",
+    "scan_bound_reached",
+    "feed_incomplete"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / stats_available
```
Added value: +{
+  "type": "boolean"
+}
```

Changed4 schema fields changedSep 8, 2026

addedInput schema / properties / post_id / exclusiveMinimum
```
Added value: +0
```
addedInput schema / properties / post_id / maximum
```
Added value: +9007199254740991
```

changedInput schema / properties / post_id / type

Previous value: -"number"New value: +"integer"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "comment_count": {
+      "$ref": "#/properties/views"
+    },
+    "delivered": {
+      "$ref": "#/properties/views"
+    },
+    "estimated_value": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "found": {
+      "type": "boolean"
+    },
+    "id": {
+      "$ref": "#/properties/post_id"
+    },
+    "note": {
+      "type": "string"
+    },
+    "opened": {
+      "$ref": "#/properties/views"
+    },
+    "post_date": {
+      "$ref": "#/properties/title"
+    },
+    "post_id": {
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "type": "integer"
+    },
+    "reaction_count": {
+      "$ref": "#/properties/views"
+    },
+    "sent": {
+      "$ref": "#/properties/views"
+    },
+    "signups": {
+      "$ref": "#/properties/views"
+    },
+    "subscribes": {
+      "$ref": "#/properties/views"
+    },
+    "title": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "views": {
+      "anyOf": [
+        {
+          "maximum": 9007199254740991,
+          "minimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "found"
+  ],
+  "type": "object"
+}

Addedv0.5.0Jul 10, 2026

TDQS

A4.5/5.0

Behavior5/5

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

The description goes far beyond the readOnlyHint annotation by disclosing the one-read success path, the up-to-10-read scan fallback, the bounded semantics of a feed-scan miss, stats_available behavior, and the fact that per-post rates are upstream fractions. It also explicitly states 'No writes,' which is consistent with readOnlyHint=true.

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 front-loaded with the core action and immediately scannable metrics list. The trailing edge-case details—fallback scan limits, miss semantics, stats_available, and rate fractions—are dense but each adds necessary behavioral context. No 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?

With an output schema present, return values need not be spelled out. The description covers prerequisites, error-triggered fallback behavior, read limits, miss semantics, and special values like stats_available, making the tool's behavior fully predictable for an agent about to invoke it.

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

Parameters3/5

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

The schema already fully documents the single post_id parameter (100% coverage). The description reinforces that the ID must reference a published post and mentions ID mismatches, but it does not add new syntactic or format-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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?

The description opens with a specific verb and resource: 'Get performance stats... for a published post by ID' and enumerates the exact metrics returned. It is unambiguous and implicitly distinguishes this per-post analytics tool from related siblings like get_publication_stats and get_post.

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?

It clearly states the required precondition ('requires a published post with a post date') and explains the fallback scan behavior for drafts and errors. However, it does not explicitly say when to prefer this tool over sibling analytics or retrieval tools, or when not to use it.

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