# List an Instagram user's recent posts

Returns an Instagram user's recent posts, with caption, media type, date and engagement counts, a page at a time. Use it to follow an account's content.

Tool `instagram.user.posts` on Instagram. Contract version 1, released 2026-10-27.

## 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.user.posts/calls \
  -H "Authorization: Bearer $VOXORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"user_id":"25025320"}}'
```

Python:

```python
import os

import httpx

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

TypeScript:

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

MCP (`tools/call` params):

```json
{
  "name": "call_tool",
  "arguments": {
    "tool": "instagram.user.posts",
    "input": {
      "user_id": "25025320"
    }
  }
}
```

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 |
| --- | --- | --- | --- | --- |
| `user_id` | string | Yes |  | Instagram's numeric identifier of the user. Take it from user.id of instagram.user.profile. Matches `^[0-9]+$`. |
| `next_page_token` | string | No |  | Fetches the next page. Take it from pagination.next_page_token of the previous page, and send the same user_id. |

## 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. |
| `url` | string | No | Address of the post on instagram.com. |
| `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`. |
| `text` | string | No | The post's caption, hashtags and mentions included. |
| `published_at` | string | No | When the post was published, in ISO 8601. |
| `duration_ms` | integer | No | Length of the video, in milliseconds. |
| `preview_image_url` | string | No | Address of the post's cover image. Instagram's media addresses expire. |
| `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. |
| `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 |  |
| `hashtags` | array of string | No | Each hashtag in the caption, without the |
| `mentioned_usernames` | array of string | No | Handle of each account the caption mentions, without the @. |

### 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": "4017275189435174347",
      "shortcode": "DfAOoAXRg3L",
      "url": null,
      "media_type": "video",
      "text": "An original, straight from the studio 🎶⁣\n⁣\n@lolabllue is a musician figuring it out one song at a time.⁣\n⁣\n“I’ll write about whatever I’m feeling that day, whatever I wanna say in that moment. I always try to have fun with it and not take myself too seriously.”⁣\n⁣\nVideo and music by @lolabllue",
      "published_at": "2026-10-27T15:59:33Z",
      "duration_ms": null,
      "preview_image_url": "https://instagram.fbcn2-1.fna.fbcdn.net/v/t51.82787-15/869628235_2694402707643736_8310406933256165894_n.jpg?stp=dst-jpg_e15_p240x240_tt6&_nc_cat=1&ig_cache_key=NDAxNzI3NTE4OTQzNTE3NDM0NzI2OTQ0MDI3MDQzMTA0MDM%3D.3-ccb7-5&ccb=7-5&_nc_sid=58cdad&efg=eyJ2ZW5jb2RlX3RhZyI6IkNMSVBTLnhwaWRzLjEwODAuc2RyLnZpZGVvX3VzZXJfdXBsb2FkZWRfdGh1bWJuYWlsLkMzIn0%3D&_nc_ohc=fTMdnZ6vLNUQ7kNvwFIVidY&_nc_oc=AdqtbiJPEdLg7FqrbO3gJ22e7Z0O60xGHnkyeyB2Xyes82UlanFbnIVNFtGlHScRFrM&_nc_ad=z-m&_nc_cid=0&_nc_zt=23&_nc_ht=instagram.fbcn2-1.fna&_nc_gid=jI8LE3FpPbMENQaa2UUewg&_nc_ss=7c3ba&oh=00_AQRzr-0HPYsupa2fOd7oPk9xbPzd4pjedd1Xr6YN7RHkuA&oe=6AE73D3F",
      "author_id": "25025320",
      "author_username": "instagram",
      "author_name": "Instagram",
      "author_image_url": "https://instagram.fbcn2-1.fna.fbcdn.net/v/t51.82787-19/550891366_18667771684001321_1383210656577177067_n.jpg?stp=dst-jpg_e0_s150x150_tt6&_nc_cat=1&ig_cache_key=GGbv1SApFvlLPVJCAOtF0XrDJjITbmNDAQAB1501500j-ccb7-5&ccb=7-5&_nc_sid=669407&efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLnd3dy4xMDgwLkMzIn0%3D&_nc_ohc=0JxmKDYmCiYQ7kNvwH4ME3h&_nc_oc=AdqaMW5eK1i8zCKz_Sonmu_1jhxHPiw7hfhC31A9BhPSfLxEwSbAUWMIhoqifHt3z6c&_nc_ad=z-m&_nc_cid=0&_nc_zt=24&_nc_ht=instagram.fbcn2-1.fna&_nc_gid=jI8LE3FpPbMENQaa2UUewg&_nc_ss=7c3ba&oh=00_AQQWk8xlDlZkd4rcTcbfOfBcVFaWtL4gZgz4-PzDhYX0SQ&oe=6AE73467",
      "author_verified": true,
      "view_count": 37825782,
      "like_count": 152581,
      "comment_count": 5254,
      "hashtags": null,
      "mentioned_usernames": null
    },
    {
      "id": "4016654745137228714",
      "shortcode": "De-BjWlSquq",
      "url": null,
      "media_type": "video",
      "text": "beware: meownster under the bed 🐱⁣\n⁣\n#InTheMoment⁣\n⁣\nVideo by @itsmariahmeow⁣\n⁣\nMusic by @myuusic",
      "published_at": "2026-10-26T19:24:34Z",
      "duration_ms": null,
      "preview_image_url": "https://instagram.fbcn2-1.fna.fbcdn.net/v/t51.82787-15/865960187_1639440901154492_6932448963667447283_n.jpg?stp=dst-jpg_e15_p240x240_tt6&_nc_cat=1&ig_cache_key=NDAxNjY1NDc0NTEzNzIyODcxNDE2Mzk0NDA4OTc4MjExNTk%3D.3-ccb7-5&ccb=7-5&_nc_sid=58cdad&efg=eyJ2ZW5jb2RlX3RhZyI6IkNMSVBTLnhwaWRzLjcyMC5zZHIudmlkZW9fdXNlcl91cGxvYWRlZF90aHVtYm5haWwuQzMifQ%3D%3D&_nc_ohc=97FbWbOMafIQ7kNvwEh7So3&_nc_oc=AdqsI66_h7Jcn_VXgqyXGYB5HY71kssPKMT3qbV4bcxWfQOk9mCWfzOCM58fD1EsKF4&_nc_ad=z-m&_nc_cid=0&_nc_zt=23&_nc_ht=instagram.fbcn2-1.fna&_nc_gid=jI8LE3FpPbMENQaa2UUewg&_nc_ss=7c3ba&oh=00_AQQPJpiNVf8smWQxxjtFN1ltoJ1eLJCg3SVw5HnbTT4oQg&oe=6AE74AD6",
      "author_id": "25025320",
      "author_username": "instagram",
      "author_name": "Instagram",
      "author_image_url": "https://instagram.fbcn2-1.fna.fbcdn.net/v/t51.82787-19/550891366_18667771684001321_1383210656577177067_n.jpg?stp=dst-jpg_e0_s150x150_tt6&_nc_cat=1&ig_cache_key=GGbv1SApFvlLPVJCAOtF0XrDJjITbmNDAQAB1501500j-ccb7-5&ccb=7-5&_nc_sid=669407&efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLnd3dy4xMDgwLkMzIn0%3D&_nc_ohc=0JxmKDYmCiYQ7kNvwH4ME3h&_nc_oc=AdqaMW5eK1i8zCKz_Sonmu_1jhxHPiw7hfhC31A9BhPSfLxEwSbAUWMIhoqifHt3z6c&_nc_ad=z-m&_nc_cid=0&_nc_zt=24&_nc_ht=instagram.fbcn2-1.fna&_nc_gid=jI8LE3FpPbMENQaa2UUewg&_nc_ss=7c3ba&oh=00_AQQWk8xlDlZkd4rcTcbfOfBcVFaWtL4gZgz4-PzDhYX0SQ&oe=6AE73467",
      "author_verified": true,
      "view_count": 59509427,
      "like_count": 445739,
      "comment_count": 7017,
      "hashtags": null,
      "mentioned_usernames": null
    },
    {
      "id": "4014515767420229441",
      "shortcode": "De2bNIWSZdB",
      "url": null,
      "media_type": "video",
      "text": "this paper art? peak cozy vibes 🍂📚⁣\n⁣\n#InTheMoment⁣\n⁣\nVideo by @alleymcglynn⁣\n⁣\nMusic by @morunas.music",
      "published_at": "2026-10-23T20:35:02Z",
      "duration_ms": null,
      "preview_image_url": "https://instagram.fbcn2-1.fna.fbcdn.net/v/t51.82787-15/864469176_1600319478243640_5690886848810458736_n.jpg?stp=dst-jpg_e15_p240x240_tt6&_nc_cat=1&ig_cache_key=NDAxNDUxNTc2NzQyMDIyOTQ0MTE2MDAzMTk0NzQ5MTAzMDc%3D.3-ccb7-5&ccb=7-5&_nc_sid=58cdad&efg=eyJ2ZW5jb2RlX3RhZyI6IkNMSVBTLnhwaWRzLjEwODAuc2RyLnZpZGVvX3VzZXJfdXBsb2FkZWRfdGh1bWJuYWlsLkMzIn0%3D&_nc_ohc=Sup01EqA_NMQ7kNvwFbVrbL&_nc_oc=AdrDJuy4nqNulLXXdjRQjxhtGKrV9I5QqI_HsSwA40JpW3DxTKLjW72CKHflt3nnHwY&_nc_ad=z-m&_nc_cid=0&_nc_zt=23&_nc_ht=instagram.fbcn2-1.fna&_nc_gid=jI8LE3FpPbMENQaa2UUewg&_nc_ss=7c3ba&oh=00_AQTzLL1yq_xcHNPT6TQUhfG7aFvdA6ljDTeTE1IgUw7I3A&oe=6AE75B6E",
      "author_id": "25025320",
      "author_username": "instagram",
      "author_name": "Instagram",
      "author_image_url": "https://instagram.fbcn2-1.fna.fbcdn.net/v/t51.82787-19/550891366_18667771684001321_1383210656577177067_n.jpg?stp=dst-jpg_e0_s150x150_tt6&_nc_cat=1&ig_cache_key=GGbv1SApFvlLPVJCAOtF0XrDJjITbmNDAQAB1501500j-ccb7-5&ccb=7-5&_nc_sid=669407&efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLnd3dy4xMDgwLkMzIn0%3D&_nc_ohc=0JxmKDYmCiYQ7kNvwH4ME3h&_nc_oc=AdqaMW5eK1i8zCKz_Sonmu_1jhxHPiw7hfhC31A9BhPSfLxEwSbAUWMIhoqifHt3z6c&_nc_ad=z-m&_nc_cid=0&_nc_zt=24&_nc_ht=instagram.fbcn2-1.fna&_nc_gid=jI8LE3FpPbMENQaa2UUewg&_nc_ss=7c3ba&oh=00_AQQWk8xlDlZkd4rcTcbfOfBcVFaWtL4gZgz4-PzDhYX0SQ&oe=6AE73467",
      "author_verified": true,
      "view_count": 73063162,
      "like_count": 373375,
      "comment_count": 17204,
      "hashtags": null,
      "mentioned_usernames": null
    }
  ],
  "pagination": {
    "next_page_token": "pt1.dGlraHViOjM5OTc3OTg1NDgwMDIyMzg5NDNfMjUwMjUzMjA"
  }
}
```