# Mentions

See where other people tag your accounts on Instagram, Facebook and LinkedIn, reply to Instagram mentions, and search and engage on X.

Mentions are posts and comments by other people that tag one of your accounts. They do not show up under your own posts, so they are easy to miss. Pozy collects them into one list, and adds search and engagement tools for X.

## List mentions

`GET /v1/inbox/mentions` returns mentions of your connected accounts from the last 7 days, newest first.

```bash cURL
curl "https://api.pozy.ai/v1/inbox/mentions?profileId=6650c1e2a3b4c5d6e7f80911&limit=25" \
  -H "Authorization: Bearer $POZY_API_KEY"
```
```ts Node
const res = await fetch("https://api.pozy.ai/v1/inbox/mentions?profileId=6650c1e2a3b4c5d6e7f80911&limit=25", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

for (const m of data.data) console.log(m.platform, m.type, m.authorUsername, m.content);
```
```python Python
import os
import requests

resp = requests.get(
    "https://api.pozy.ai/v1/inbox/mentions",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={"profileId": "6650c1e2a3b4c5d6e7f80911", "limit": 25},
    timeout=30,
)
for m in resp.json()["data"]:
    print(m["platform"], m["type"], m["content"])
```

Each mention has a `platform`, a `type` (`caption`, `post` or `comment`), the author, the text, a `permalink`, and the ids you need to answer it (`mediaId`, `commentId`, `postId`).

| Platform | What is collected | Can you reply here? |
| --- | --- | --- |
| Instagram | Someone tags the account in a comment on their own media, or in a caption. Accounts connected through Facebook Login only | Yes |
| Facebook | Someone tags the Page in a post or a comment | No. Open the `permalink` |
| LinkedIn | Mentions of a company page | No |

Comments on your own posts are never listed as mentions, even when they contain your handle; they are in [Comments](https://pozy.ai/docs/inbox/comments). On Instagram the text is fetched in the background after the first request, so `content` can be empty on the first read.

## Reply to an Instagram mention

`POST /v1/inbox/mentions/reply` answers in one of two ways, depending on whether you pass `commentId`:

- **Comment mention** (you were tagged inside a comment): send `mediaId` and `commentId`. Your reply goes under that comment.
- **Caption mention** (you were tagged in the caption): send `mediaId` only. Your reply is posted as a comment on their media.

```bash
curl -X POST https://api.pozy.ai/v1/inbox/mentions/reply \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "accountId": "6650c1e2a3b4c5d6e7f80a22", "mediaId": "17899887766554433", "message": "Thanks for the shout-out!" }'
```

Instagram's API does not support replying to story mentions. To answer those with a DM, use a [comment automation](https://pozy.ai/docs/automations/comment-to-dm) with the `story_mention` trigger or a [workflow](https://pozy.ai/docs/automations/workflows).

## Tagged posts

Tags in photos are not the same as @mentions. Read them separately:

- [`GET /v1/accounts/{accountId}/instagram/tags`](https://pozy.ai/docs/api/listInstagramTaggedMedia) lists media the Instagram account is tagged in.
- [`GET /v1/accounts/{accountId}/facebook-tagged-posts`](https://pozy.ai/docs/api/listFacebookTaggedPosts) lists posts a Page is tagged in, and [`facebook-visitor-posts`](https://pozy.ai/docs/api/listFacebookVisitorPosts) lists posts visitors left on the Page.
- To open one Instagram caption or comment mention by id, use [`instagram/mentions/media/{mediaId}`](https://pozy.ai/docs/api/getInstagramMentionedMedia) or [`instagram/mentions/comments/{commentId}`](https://pozy.ai/docs/api/getInstagramMentionedComment).

## Mention someone on LinkedIn

To tag a person or company in a LinkedIn post, put their profile or company URL inside `@[...]` in the post content, for example `@[https://www.linkedin.com/company/acme]`. Pozy resolves it to LinkedIn's own name when the post publishes.

To preview the result, or get ready-made markup, call [`GET /v1/accounts/{accountId}/linkedin-mentions?url=...`](https://pozy.ai/docs/api/getLinkedInMentions). It returns the URN and a `mentionFormat` such as `@[Acme](urn:li:organization:123)` you can paste into content. Resolving a person's profile URL needs the connected member to administer at least one company page.

## X: search and engagement

X has no mentions feed through this list. Use search instead, then act on what you find from any connected X account.

| Task | Call |
| --- | --- |
| Search recent posts (last 7 days, X search operators) | `GET /v1/twitter/search?accountId=&query=` |
| Look up one post by id | `GET /v1/twitter/tweet?accountId=&tweetId=` |
| Repost, undo | `POST` / `DELETE /v1/twitter/retweet` with `accountId` and `tweetId` |
| Bookmark, remove | `POST` / `DELETE /v1/twitter/bookmark` with `accountId` and `tweetId` |
| Follow, unfollow | `POST` / `DELETE /v1/twitter/follow` with `accountId` and `targetUserId` |

```bash
curl "https://api.pozy.ai/v1/twitter/search?accountId=6650c1e2a3b4c5d6e7f80a33&query=%40acme%20-is%3Aretweet&limit=25" \
  -H "Authorization: Bearer $POZY_API_KEY"
```

- X allows 50 requests per 15 minutes for each of repost, bookmark and follow. Reposts also count against X's posting limit.
- Bookmarks and follows need the matching X permissions. A `403` usually means the account must be reconnected to grant them.
- Following a protected account returns `pending_follow: true` until they accept.
- Every X read and write is billed per call. See [Pricing](https://pozy.ai/docs/billing).

## Reddit search

Reddit search, subreddit feeds and post comments (`/v1/reddit/*`) answer `503` with `PLATFORM_DISABLED` while Reddit blocks third-party apps. Reddit Ads are not affected. See [Reddit](https://pozy.ai/docs/platforms/reddit).

## Endpoints

| Endpoint | What it does |
| --- | --- |
| [`GET /v1/accounts/{accountId}/linkedin-mentions`](https://pozy.ai/docs/api/getLinkedInMentions) | Resolve LinkedIn mention |
| [`GET /v1/inbox/mentions`](https://pozy.ai/docs/api/listInboxMentions) | List mentions |
| [`POST /v1/inbox/mentions/reply`](https://pozy.ai/docs/api/replyToMention) | Reply to a mention |
| [`GET /v1/reddit/search`](https://pozy.ai/docs/api/searchReddit) | Search posts |
| [`GET /v1/reddit/feed`](https://pozy.ai/docs/api/getRedditFeed) | Get subreddit feed |
| [`GET /v1/reddit/comments/{postId}`](https://pozy.ai/docs/api/getRedditPostComments) | Get the comments of a Reddit post |
| [`POST /v1/twitter/retweet`](https://pozy.ai/docs/api/retweetPost) | Retweet a post |
| [`DELETE /v1/twitter/retweet`](https://pozy.ai/docs/api/undoRetweet) | Undo retweet |
| [`POST /v1/twitter/bookmark`](https://pozy.ai/docs/api/bookmarkPost) | Bookmark a tweet |
| [`DELETE /v1/twitter/bookmark`](https://pozy.ai/docs/api/removeBookmark) | Remove bookmark |
| [`POST /v1/twitter/follow`](https://pozy.ai/docs/api/followUser) | Follow a user |
| [`DELETE /v1/twitter/follow`](https://pozy.ai/docs/api/unfollowUser) | Unfollow a user |
| [`GET /v1/twitter/search`](https://pozy.ai/docs/api/searchTweets) | Search recent tweets |
| [`GET /v1/twitter/tweet`](https://pozy.ai/docs/api/getTweet) | Look up a tweet |