History

---
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`](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.)