> For the complete documentation index, see [llms.txt](https://docs.replycorp.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.replycorp.io/reporting-api-and-mcp.md). # Reporting API & MCP (Growth+) The Reporting API gives your systems — and your AI agents — programmatic read access to the same campaign insights that power the ReplyCorp dashboard: campaign stats, per-post analytics, conversions with attribution, and engagement data. It is available on the **Growth and Enterprise tiers**. The Base tier includes conversion posting and reconciliation through the API (see [API Documentation](/api-documentation.md)) and full dashboard access with CSV export, but not programmatic reads. To upgrade, visit your billing settings or contact . ## Authentication All endpoints use your organization API key — the same key you use for `POST /conversions` — sent in the `X-API-Key` header: ```bash curl https://api.replycorp.io/api/v1/campaigns \ -H "X-API-Key: YOUR_API_KEY" ``` If your organization is not on an eligible tier, read endpoints return `403`: ```json { "error": "The read/reporting API requires the Growth tier or above. Conversion posting (POST /campaigns/:id/conversions) and conversion reconciliation remain available on your plan. Upgrade to Growth to enable reporting reads.", "code": "plan_capability_denied", "capability": "reporting_api", "plan": "CONVERSION_INTELLIGENCE" } ``` Dashboard sessions are never tier-gated — this applies only to API-key access. ## Rate limit Reporting reads are limited to **600 requests per hour per organization**. Standard `RateLimit-*` response headers report your remaining quota; exceeding it returns `429`. Conversion posting is not affected by this limit. ## Endpoints Base URL: `https://api.replycorp.io/api/v1` ### List campaigns `GET /campaigns?page=1&limit=10&status=ACTIVE` Your organization's campaigns with ids, names, status, and participant/connection/event counts. Use this to discover campaign ids for the other endpoints. `limit` max 50. ### Campaign stats `GET /campaigns/{campaignId}/stats` Summary totals for a campaign: ```json { "stats": { "totalEngagers": 50, "totalEngagements": 121, "totalSales": 2, "totalRevenue": 1234, "activeDaily": 0, "activeWeekly": 16, "lastUpdated": "2026-10-14T15:25:51.106Z" } } ``` ### Campaign stats history `GET /campaigns/{campaignId}/stats/historical` Historical time series of campaign stats, for trend analysis. ### Per-post analytics `GET /campaigns/{campaignId}/stats/posts?authorScope=others` Per-post performance: engagements, conversions, and revenue attributed to each tracked post, plus featured posts. The richest source for "which posts and creators drove results" questions. * `authorScope` (optional): `own` for the brand's posts, `others` for community posts; omit for all. Each row in `posts`: ```json { "tweetId": "1950000000000000001", "tweetText": "...", "tweetAuthorHandle": "creator_handle", "tweetAuthorId": "4400000001", "platform": "x", "postUrl": "https://x.com/creator_handle/status/1950000000000000001", "engagementCount": 128, "engagementsByType": { "RETWEET": 90, "QUOTE": 38 }, "conversionCount": 6, "conversionsByType": { "purchase": 6 }, "totalRevenue": 480, "connectionsCreated": 12, "disclosureQualified": true, "media": { "assetCount": 2, "mediaTypes": ["IMAGE", "VIDEO"], "disclosureDetected": true, "disclosureTypes": ["overlay_text", "spoken"], "visualThemes": ["unboxing", "product demo"] }, "postedAt": "2026-10-01T10:00:00.000Z" } ``` `media` summarizes the post's captured images/videos and their AI analysis (available on campaigns with media analysis enabled; `null` when the post has no media): * `disclosureDetected`: whether any analyzed asset carries an in-media disclosure — burned-in `#ad` overlay text, a platform paid-partnership label, a sponsor logo watermark, or a spoken sponsorship mention in video audio. `null` while analysis is pending. * `disclosureTypes`: which disclosure channels were found (`overlay_text`, `platform_label`, `logo_watermark`, `spoken`, `other`). * `visualThemes`: content themes detected in the media (e.g. `unboxing`, `product demo`) — useful for correlating imagery with conversions. A post qualifies for disclosure (`disclosureQualified`) if **either** its text or its media discloses the material connection. The response also includes `engagementTypes`, `conversionTypes`, and `featuredPosts`. ### Recent conversions `GET /campaigns/{campaignId}/conversions?limit=20` Most recent conversions with type, value, timestamp, metadata, and the converting participant. `limit` max 100. ### Conversion events with attribution `GET /campaigns/{campaignId}/conversion-events` Event-level conversions with primary post attribution and the buyers' engagement trail — the raw feed behind the Conversion Intelligence workspace. Large responses are server-capped; the response flags indicate truncation. ### AI conversion insights `GET /campaigns/{campaignId}/conversion-intelligence` Cached AI-generated insights (signals and standout posts). Returns `{ "status": "pending" }` (or another non-`ready` status) when insights have not been generated yet; generation happens from the dashboard. ### Post engagers `GET /campaigns/{campaignId}/posts/{postId}/engagers?limit=100` Who reposted or quoted a specific X post tracked by the campaign. `postId` is the numeric X post id. Supports `type` (`repost` | `quote`), `since` (ISO timestamp, filtered on ingest time), `limit` (max 200), and cursor paging via `nextCursor`. `GET /campaigns/{campaignId}/posts/{postId}/engagement-check?twitterId={id}` answers the single-user form of the same question. ### Leaderboard pull `GET /campaigns/{campaignId}/leaderboard-pull` Full leaderboard with private fields for building custom leaderboards. Documented under [API Documentation → Deprecated Features](/api-documentation.md#deprecated-features); API-key access now also requires Growth+. ## MCP: connect your AI agent ReplyCorp ships a built-in [Model Context Protocol](https://modelcontextprotocol.io) server, so agents like Claude, ChatGPT, and Cursor can discover and call the reporting tools themselves — ask "which creators drove revenue for us last week?" and the agent pulls the live data. * **Endpoint:** `https://api.replycorp.io/api/v1/mcp` * **Transport:** MCP Streamable HTTP * **Auth:** your organization API key in the `X-API-Key` header * **Access:** Growth tier and above; read-only Typical client configuration (exact format varies by client): ```json { "mcpServers": { "replycorp": { "url": "https://api.replycorp.io/api/v1/mcp", "headers": { "X-API-Key": "YOUR_API_KEY" } } } } ``` Claude Code CLI: ```bash claude mcp add --transport http replycorp https://api.replycorp.io/api/v1/mcp \ --header "X-API-Key: YOUR_API_KEY" ``` ### Available tools | Tool | What it returns | | ------------------------ | ----------------------------------------------------------------------- | | `list_campaigns` | Your campaigns with ids, names, status, and counts — the starting point | | `get_campaign_stats` | Summary stats for one campaign | | `get_stats_history` | Historical stats time series for trend questions | | `get_post_analytics` | Per-post engagements, conversions, and revenue (supports `authorScope`) | | `list_conversions` | Most recent conversions with values and participants | | `list_conversion_events` | Event-level conversions with attribution and engagement trails | | `get_ai_insights` | Cached AI-generated conversion insights | | `get_post_engagers` | Who reposted/quoted a specific post, paged | Every tool call goes through the same authentication, tier checks, and rate limits as the REST endpoints above. ## Support Questions or access requests: