| name | history |
| description | Post history for the Ayrshare MCP server — list past and scheduled posts, optionally filtered by recency, platform, and status. Use whenever someone wants to see what's been posted: "show my recent posts", "what did we publish last week", "history for this client", "did that scheduled post go out", "list our LinkedIn posts", or to look up a post id for analytics. Also the verification step after onboarding a client — confirming their accounts linked — and the way to find a NATIVE Social Post ID for analytics on a post that wasn't created through Ayrshare. Trigger when calling `mcp__ayrshare__get_post_history` or `mcp__ayrshare__get_platform_history`, and even without the word "Ayrshare" — if the user wants a log of social posts through an AI assistant, this is the skill. For the shared auth model and the full onboarding sequence, see `../getting-started/SKILL.md`.
|
Ayrshare MCP — History
Two tools:
mcp__ayrshare__get_post_history — lists posts sent via Ayrshare (returns Ayrshare Post IDs). The default "what have we posted" tool, and the onboarding verification step.mcp__ayrshare__get_platform_history — returns native social posts, including posts not made through Ayrshare (returns native Social Post IDs). This is how you find a native Social Post ID to feed mcp__ayrshare__get_post_analytics_by_social_id.
Both are profile-scoped: choose the profile with the profileKey argument or the Profile-Key header (see Auth; the argument wins when both are set).
Functions
| Tool | Purpose | Method + Endpoint | Required inputs | Optional inputs |
|---|
mcp__ayrshare__get_post_history | Retrieve history of posts sent via Ayrshare (past + scheduled); returns Ayrshare Post IDs | GET /history | — | limit (1-1000, default 25), platforms (array), startDate/endDate (ISO 8601), lastDays (default 30, 0=all), status, type (immediate|scheduled), autoRepostId |
mcp__ayrshare__get_platform_history | Retrieve native social posts (incl. posts not made via Ayrshare); returns native Social Post IDs | GET /history/:platform | platform (one enum value) | limit (1-500), skipAnalytics, pagePublished (FB), userId/userName (X), next (cursor), since/until (FB ISO dates), dataType (posts|stories) |
Full input schemas and example payloads/responses are in references/schemas.md.
Auth
Both tools are profile-scoped: choose the profile with an optional profileKey tool argument or the Profile-Key connection header (the argument wins when both are set). Pass profileKey on the call to act as one client for that call, or set the Profile-Key header (.mcp.json headers) to default the whole connection to it; with neither, calls act on the account's primary/Business profile. Full model: ../getting-started/SKILL.md.
Exception, get_platform_history userId/userName (Twitter/X): when you target a specific X user by userId (numeric Twitter ID) or userName (handle), that lookup must use the API key only; it is not profile-scoped. Supplying a profileKey (argument or Profile-Key header) alongside userId/userName returns Error 400. Every other history call (and get_post_history entirely) is profile-scoped as above. See references/schemas.md.
Usage guidance
- Your profile selection decides whose history you see. Pass
profileKey as the argument (per call; it wins) or set the connection's Profile-Key header → that profile's posts. With neither → the account's primary/Business profile. Be deliberate about which profile you're targeting.
get_post_history filters are all optional. Use lastDays to bound recency (default 30; pass 0 for all time), startDate/endDate for an explicit ISO 8601 window, platforms to narrow to a subset of networks, status to filter by lifecycle state (awaiting approval, deleted, error, paused, pending, processing, success), and limit to cap results (1-1000, default 25). Omit them all for the default recent history.- Onboarding verification. After a client completes OAuth via the JWT link, call
get_post_history scoped to their profile (pass their profileKey as the argument, or set the connection's Profile-Key header) to confirm the connection succeeded and surface their existing posts. This is the verification step in the onboarding sequence in ../getting-started/SKILL.md.
- Looking up an Ayrshare Post ID?
get_post_history returns each post's Ayrshare id — the id you feed to mcp__ayrshare__get_post_analytics and mcp__ayrshare__get_post for Ayrshare-sent posts.
- Finding a native Social Post ID (for posts not sent via Ayrshare). Call
get_platform_history with the platform (required). It returns native social posts — including posts not made through Ayrshare — each with a native Social Post id. That native id is exactly what mcp__ayrshare__get_post_analytics_by_social_id needs (native id + platform). So get_platform_history is how you find the native ids to feed analytics-by-social-id. See the Analytics skill for the analytics side of this workflow.
Gotchas
- Be deliberate about scope. Whose history you get is set by the
profileKey argument (per call; it wins) or the connection's Profile-Key header; with neither it's the primary profile, and the call succeeds regardless. Confirm you're targeting the right profile before trusting the results.
- Two different tools, two different id types.
get_post_history returns Ayrshare Post IDs (for get_post_analytics, get_post, retry_post, update_post). get_platform_history returns native Social Post IDs (for get_post_analytics_by_social_id). Don't feed one tool's ids to a path expecting the other.
get_platform_history requires platform. It is GET /history/:platform, so exactly one platform is required: one of bluesky, facebook, instagram, linkedin, pinterest, snapchat, threads, tiktok, twitter, youtube. (Note this 10-platform history set excludes gmb, reddit, and telegram, which the 13-platform POST set includes.)get_post_history platforms is plural and an array. It accepts a subset of the 13 POST platforms (twitter, facebook, instagram, linkedin, tiktok, youtube, pinterest, reddit, telegram, gmb, bluesky, snapchat, threads) and filters within the already-chosen profile scope — it does not change scope.- This is the onboarding verification step. If you reached here as part of onboarding, the connection should already be scoped to the new client's
Profile-Key; verify with get_post_history. See the onboarding sequence in ../getting-started/SKILL.md.
- An empty result isn't an error. A freshly onboarded profile with no posts yet legitimately returns an empty history. During onboarding, that confirms the account is linked, just unused.
- On failure, call
mcp__ayrshare__explain_error, then surface it — don't loop. These are reads, but a 4xx (bad filter, unsupported platform, wrong scope) won't fix itself on retry. Translate the error via mcp__ayrshare__explain_error and present it; 429 gets at most one retry. (Mirrors the global retry-safety rule.)
