API reference

Instagram Mentions API

One endpoint that does what the Monitor Mentions page does: give it a handle, hashtags or phrases, get back the public Instagram posts that mention them, each with the search that found it.

Get a free key Pricing

Quick start

Sign in on the dashboard and create a key. It starts mm_mon_ and is shown once.
Send it as Authorization: Bearer mm_mon_… or as an x-api-key header.
POST what you are watching. That is all of it.

curl -X POST https://www.monitormentions.com/api/v1/mentions/search \
  -H "Authorization: Bearer $MM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handle": "liquiddeath", "keywords": ["murder your thirst", "deathwish"]}'

Response shape

{
  "entity":   { "handle": "liquiddeath" },
  "account":  { "handle", "name", "followers", "is_verified", ... },
  "credits":  { "charged", "remaining", "monthly" },
  "summary":  { "posts", "creators", "videos", "newest", "oldest",
                "terms": [{ "term", "posts" }] },
  "posts": [{
    "id", "url", "author", "caption", "thumbnail", "is_video",
    "taken_at", "likes", "comments",
    "found_by": { "method": "hashtag | tagged | phrase", "term" }
  }],
  "failed": [{ "method", "term" }]
}

POST /api/v1/mentions/search

Runs every search for the entity now and answers when they are back. Give a handle, at least one term, or both. Up to 5 terms per call; for more, make more calls.

Request body

Field	Type	What it does
`handle`	string, optional	An Instagram handle, with or without the @, or a profile URL. Adds a lookup, its hashtag and its tagged tab.
`keywords`	string[] or string, optional	Words and phrases. One word is searched as a hashtag; two or more as a phrase. Comma-separated strings work too.
`hashtags`	string[], optional	Always searched as a hashtag. Spaces are dropped, since a tag cannot hold one.

Each post

`id`	Instagram's id for the post
`url`	Link to the post
`author`	Handle of the account that posted it
`caption`	The caption, or null
`thumbnail`	Image URL from Instagram. These expire, so store the image if you need it later
`is_video`	true for reels and videos
`taken_at`	ISO 8601 timestamp, or null
`likes, comments`	Counts as Instagram reported them, or null when hidden
`found_by`	{ method, term }: the search that found it. method is hashtag, tagged or phrase

A post found by two searches is returned once, under the first one that found it. summary counts posts, accounts and posts per term, and nothing else: there is no reach or sentiment field, because we do not measure either.

What a call costs

One credit per search, and the searches are listed before you send anything:

`handle`	3 credits: the account lookup, its hashtag, its tagged tab
each keyword or hashtag	1 credit
the same search again, same UTC day	free

A handle that does not exist costs 1 credit, the lookup, and the other searches are not run. A search that fails upstream is still counted, because we cannot tell whether it was metered first; the response lists it under failed. Every response carries x-credits-remaining.

GET /api/v1/mentions/usage

Free. Returns plan, monthly, used, remaining and resets_on. Credits reset on the 1st of each month, UTC.

Errors

Every error is JSON: {"error": "…", "status": 400}.

`400`	Nothing to search, a bad handle, or more than 5 terms. The message says which.
`401`	Missing, invalid or revoked key.
`404`	The handle does not exist on Instagram. Costs one credit, the lookup.
`429`	Not enough credits left this month for this search. Nothing is charged.
`502 / 503`	Upstream or our ledger did not answer. Try again shortly.

Coming next

Watched entities: register a handle and its terms once, and we search on a schedule and POST new mentions to your webhook. If you want it, tell us what you would use it for.