# List the posts with an Instagram hashtag

Returns the Instagram posts with a hashtag, from its top, recent or reels feed, with caption, date and engagement counts, a page at a time. Use it to follow a topic on Instagram.

Tool `instagram.hashtag.posts` on Instagram. Contract version 1, released 2026-11-01.

## Example call

Over REST, send the input in the body. Over MCP, pass the same input to `call_tool`.

cURL:

```bash
curl https://api.voxoria.ai/v1/tools/instagram.hashtag.posts/calls \
  -H "Authorization: Bearer $VOXORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"hashtag":"coffee"}}'
```

Python:

```python
import os

import httpx

response = httpx.post(
    "https://api.voxoria.ai/v1/tools/instagram.hashtag.posts/calls",
    headers={"Authorization": f"Bearer {os.environ['VOXORIA_API_KEY']}"},
    json={"input": {"hashtag": "coffee"}},
    timeout=60,
)
print(response.json())
```

TypeScript:

```ts
const response = await fetch("https://api.voxoria.ai/v1/tools/instagram.hashtag.posts/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VOXORIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"input": {"hashtag": "coffee"}}),
});
console.log(await response.json());
```

MCP (`tools/call` params):

```json
{
  "name": "call_tool",
  "arguments": {
    "tool": "instagram.hashtag.posts",
    "input": {
      "hashtag": "coffee"
    }
  }
}
```

Both return [the full response](/docs/call-response.md): the call's ID, status and cost, with this tool's result in `output`.

## Input

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `hashtag` | string | Yes |  | The hashtag, without the Matches `^[^#\s]+$`. |
| `feed` | string | No |  | Which of the hashtag's feeds to read: top, recent or reels. Left out, the source's own choice, which may be either top or recent. One of `top`, `recent`, `reels`. |
| `next_page_token` | string | No |  | Fetches the next page. Take it from pagination.next_page_token of the previous page, and send the same hashtag and feed. |

## Output

A successful call returns these blocks in its `output`. A field not marked required can be `null`.

### posts

A list of rows. Always present, possibly empty.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Instagram's numeric identifier of the post, as a string. |
| `shortcode` | string | No | The code in the post's address, https://www.instagram.com/p/ followed by it. instagram.post.comments takes it as shortcode. |
| `text` | string | No | The post's caption, hashtags and mentions included. |
| `published_at` | string | No | When the post was published, in ISO 8601. |
| `preview_image_url` | string | No | Address of the post's cover image. Instagram's media addresses expire. |
| `media_type` | string | No | What the post holds: one photo, one video (a reel included), or a carousel of several. One of `photo`, `video`, `carousel`. |
| `author_id` | string | No | Instagram's numeric identifier of the author, as a string. |
| `author_username` | string | No | The author's handle, without the @. |
| `author_name` | string | No | The author's display name. |
| `author_image_url` | string | No | Address of the author's profile picture. Instagram's media addresses expire. |
| `author_verified` | boolean | No | Whether Instagram marks the author as verified. |
| `view_count` | integer | No | Number of times the video was played. |
| `like_count` | integer | No |  |
| `comment_count` | integer | No |  |

### pagination

One object. Can be `null`. How to fetch the next page. Null on the last page.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `next_page_token` | string | Yes | Send as next_page_token to fetch the next page. |

## Example output

The `output` of a real call, each list cut to 3 items.

```json
{
  "posts": [
    {
      "id": "4020646259980257966",
      "shortcode": "DfMNHidoEqu",
      "text": "#sundayvibes 🍁☕️#coffee #milk #croissant",
      "published_at": "2026-11-01T07:35:45Z",
      "preview_image_url": "https://instagram.fbcn2-1.fna.fbcdn.net/v/t51.82787-15/880004570_18100840037385022_777369588746911096_n.jpg?stp=dst-jpg_e35_p1080x1080_sh2.08_tt6&_nc_ht=instagram.fbcn2-1.fna.fbcdn.net&_nc_cat=110&_nc_oc=Q6cZ2gEat5cNK0puiBDe_DWFgHQWLzZFhkMkH3uU8uBLPb1ybbMQJBbatfHbBtrxPfJlCCk&_nc_ohc=ukqewfNUpWEQ7kNvwESoC35&_nc_gid=tTYEC7BdwL2uDN55QGrjXQ&edm=AA0rjkIBAAAA&ccb=7-5&ig_cache_key=NDAyMDY0NjI1OTk4MDI1Nzk2Ng%3D%3D.3-ccb7-5&oh=00_AQQpfhPO9p1aW_ALzZUIzuhpQuV1Gq3GRUazCMQwkPvgbw&oe=6AECB362&_nc_sid=49ed71",
      "media_type": "photo",
      "author_id": "41600937021",
      "author_username": null,
      "author_name": null,
      "author_image_url": null,
      "author_verified": null,
      "view_count": null,
      "like_count": 0,
      "comment_count": 0
    },
    {
      "id": "4020647384333021381",
      "shortcode": "DfMNX5mRfDF",
      "text": "The essentials 🎀✨️\n\n#coffee #pilateslife #fypシ❤️💞❤️",
      "published_at": "2026-11-01T07:35:43Z",
      "preview_image_url": "https://instagram.fbcn2-1.fna.fbcdn.net/v/t51.82787-15/881258758_17906103021599954_9132226081158517895_n.jpg?stp=dst-jpg_e35_p1080x1080_sh2.08_tt6&_nc_ht=instagram.fbcn2-1.fna.fbcdn.net&_nc_cat=102&_nc_oc=Q6cZ2gEat5cNK0puiBDe_DWFgHQWLzZFhkMkH3uU8uBLPb1ybbMQJBbatfHbBtrxPfJlCCk&_nc_ohc=I-QT_3ANARAQ7kNvwFnMBBt&_nc_gid=tTYEC7BdwL2uDN55QGrjXQ&edm=AA0rjkIBAAAA&ccb=7-5&ig_cache_key=NDAyMDY0NzM4NDMzMzAyMTM4MQ%3D%3D.3-ccb7-5&oh=00_AQRiwDdjU7m_RfDcszC-7YGpToA0M9kLWES5siCC2oqF3A&oe=6AECBA27&_nc_sid=49ed71",
      "media_type": "photo",
      "author_id": "77830999953",
      "author_username": null,
      "author_name": null,
      "author_image_url": null,
      "author_verified": null,
      "view_count": null,
      "like_count": 0,
      "comment_count": 0
    },
    {
      "id": "4020647309511580859",
      "shortcode": "DfMNWz6kVy7",
      "text": "Morning colors… 🍂🍃💫 #matcha #strawberry #latte #morning #coffee",
      "published_at": "2026-11-01T07:35:31Z",
      "preview_image_url": "https://instagram.fbcn2-1.fna.fbcdn.net/v/t51.82787-15/872937601_18498269422110659_292970139637619318_n.jpg?stp=dst-jpg_e35_p1080x1080_sh2.08_tt6&_nc_ht=instagram.fbcn2-1.fna.fbcdn.net&_nc_cat=111&_nc_oc=Q6cZ2gEat5cNK0puiBDe_DWFgHQWLzZFhkMkH3uU8uBLPb1ybbMQJBbatfHbBtrxPfJlCCk&_nc_ohc=uo1oIA_KIf0Q7kNvwFM_1MY&_nc_gid=tTYEC7BdwL2uDN55QGrjXQ&edm=AA0rjkIBAAAA&ccb=7-5&ig_cache_key=NDAyMDY0NzIyOTI0NDMzMTU3MQ%3D%3D.3-ccb7-5&oh=00_AQShhhNxkcP5dNzYQyubOYVdQ_EpuPzZh53v5LBtyl3Wvg&oe=6AECC29D&_nc_sid=49ed71",
      "media_type": "carousel",
      "author_id": "3225654658",
      "author_username": null,
      "author_name": null,
      "author_image_url": null,
      "author_verified": null,
      "view_count": null,
      "like_count": 0,
      "comment_count": 0
    }
  ],
  "pagination": {
    "next_page_token": "pt1.dGlraHViOlFWRkRhbUpVZVRnNFlVbGFhVlpXYW5FM1FrSm1TemN5VFhoZmVGTnZWVWxtT1VsRkxYTmhYeTFEU25Rek5tOVhaazltUlU1TlRsWXdVa0pXVFhGTVJqRlpOM2swTTFSd2FIWnJVRU5MVTBGT1JIbGZPRVZHVWc9PQ"
  }
}
```