Instagram User Reels API

Open in ChatGPT Open in Claude Open in Gemini

A profile's reels, newest first, twelve per page, each with like, comment and play counts. Follow pagination.cursor for older reels. The first page also carries captions; later pages do not, so text is null there, and a collab reel owned by another account has authorHandle null. No page carries a publish date; fetch /v1/instagram/post for one reel's date, or set extra_fetch=true to fill each reel's publish date, caption and duration from its own page in one call: 1 credit per item fetched, up to the page size. If the reels tab is unavailable, the first page falls back to the clips in the profile grid, with captions but no counts and no cursor. An account with no public reels is an empty result, and is not charged. raw.source says which path answered. **Required:** Pass either handle or user_id. Calls cost 1 credit each. A cache hit is free, and a failed or empty response is never charged.

Try it

Prefilled with the request that produced the example below. No key yet? Get a free key.

Request

GET/v1/instagram/user-reels

Parameter Type Required Description

handle string no Handle (@nike), or a full instagram.com profile URL. Optional if user_id is given.

user_id string no Numeric user id. Skips a lookup. Take it from data.items[].authorId.

cursor string no pagination.cursor from a previous response

count number no Reels per page, 1-12. Default 12.

extra_fetch boolean no When true, fetches each item's own page to fill fields the list page leaves null. Costs 1 extra credit per page fetched, up to the page size.

max_id string no pagination.cursor from a previous response

Parameter	Type	Required	Description
handle	string	no	Handle (@nike), or a full instagram.com profile URL. Optional if `user_id` is given.
user_id	string	no	Numeric user id. Skips a lookup. Take it from `data.items[].authorId`.
cursor	string	no	`pagination.cursor` from a previous response
count	number	no	Reels per page, 1-12. Default 12.
extra_fetch	boolean	no	When true, fetches each item's own page to fill fields the list page leaves null. Costs 1 extra credit per page fetched, up to the page size.
max_id	string	no	`pagination.cursor` from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl

curl "$API/v1/instagram/user-reels?handle=natgeo&cache_max_age=7d" \
  -H "x-api-key: $KEY"

JavaScript

const query = new URLSearchParams({
  handle: 'natgeo',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/user-reels?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);

Python

import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/user-reels",
    params={
        "handle": "natgeo",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])

Example response

Captured on 2026-10-21, with raw removed and lists cut to two items. A live call returns current data.

response

{
  "success": true,
  "data": {
    "items": [
      {
        "platform": "instagram",
        "id": "Deu3BoCBbDP",
        "type": "reel",
        "url": "https://www.instagram.com/reel/Deu3BoCBbDP/",
        "title": null,
        "text": "Don't let its stubby arms fool you—Koleken inakayali was an ambush predator from the abelisaurid family that once thrived in the Southern Hemisphere. Named by National Geographic Explorer @poldiego and colleagues, Koleken inakayali's tiny forelimbs continue to puzzle experts. \n\nLearn more about Koleken inakayali at the link in bio.",
        "authorId": "787132",
        "authorHandle": "natgeo",
        "authorName": null,
        "thumbnailUrl": "https://scontent.cdninstagram.com/v/t51.82787-15/859290875_18710294083019133_9207028849151430450_n.jpg?stp=dst-jpg_e35_s640x640_tt6&_nc_cat=1&ccb=7-5&_nc_sid=18de74&efg=eyJlZmdfdGFnIjoiQ0xJUFMuYmVzdF9pbWFnZV91cmxnZW4uQzMifQ%3D%3D&_nc_ohc=CZxfb2xhPxkQ7kNvwFmx-tM&_nc_oc=AdqNUBCpWsJyiuB7oM8vHB3iYjeWpLa2MKU70b3B2FEwooZnBBGopf9jC7RSUXbjY9U&_nc_zt=23&_nc_ht=scontent.cdninstagram.com&_nc_gid=occRPwbdtJoTBac8S9zQGQ&_nc_ss=70a8c&oh=00_AQP6Qoivrkx_CyG4O3zKq_IhjNHFZY_-E4j5mi4PDGXVgA&oe=6ADE0829",
        "mediaUrls": [],
        "durationSeconds": null,
        "viewCount": 1078044,
        "likeCount": 23344,
        "commentCount": 280,
        "shareCount": null,
        "hashtags": [],
        "mentions": [
          "poldiego"
        ],
        "isSponsored": null,
        "publishedAt": null,
        "fetchedAt": "2026-10-21T01:53:06.292Z"
      },
      {
        "platform": "instagram",
        "id": "DeuQnVClIKd",
        "type": "reel",
        "url": "https://www.instagram.com/reel/DeuQnVClIKd/",
        "title": null,
        "text": "Presented by @Rolex. Deep inside a cave in the Congo, thousands of bats share their home with an unexpected predator: a dwarf crocodile. Even though she can hear the bats, catching them can be a challenge.\n\nThrough its partnership with the National Geographic Society and as part of its Perpetual Planet Initiative, #Rolex supports expeditions exploring and protecting remarkable places around the world, a selection of which are featured in Africa Earth's Wild Home. #PerpetualPlanet\n\n#AfricaEarthsWildHome now streaming on @DisneyPlus and @hulu.",
        "authorId": "414805671",
        "authorHandle": "natgeoscience",
        "authorName": null,
        "thumbnailUrl": "https://scontent.cdninstagram.com/v/t51.82787-15/861685983_18637236637021672_4516376351917560107_n.jpg?stp=dst-jpg_e35_s640x640_tt6&_nc_cat=1&ccb=7-5&_nc_sid=18de74&efg=eyJlZmdfdGFnIjoiQ0xJUFMuYmVzdF9pbWFnZV91cmxnZW4uQzMifQ%3D%3D&_nc_ohc=glGkLRqfND0Q7kNvwEpL1rZ&_nc_oc=AdpywIKf9ea5w1ttaV0dLzc0p6S8W6EFMxgtz87xIQZkcYirhuYqLwZdG9vThY7xV68&_nc_zt=23&_nc_ht=scontent.cdninstagram.com&_nc_gid=occRPwbdtJoTBac8S9zQGQ&_nc_ss=70a8c&oh=00_AQPuQXQm9P-ZfzRQJKDU-ACj8J3xBJWCQKqrSLhTTv5sIQ&oe=6ADE01E4",
        "mediaUrls": [],
        "durationSeconds": null,
        "viewCount": 934963,
        "likeCount": 27809,
        "commentCount": 121,
        "shareCount": null,
        "hashtags": [
          "Rolex",
          "PerpetualPlanet"
        ],
        "mentions": [
          "Rolex",
          "DisneyPlus"
        ],
        "isSponsored": null,
        "publishedAt": null,
        "fetchedAt": "2026-10-21T01:53:06.292Z"
      }
    ]
  },
  "pagination": {
    "cursor": "eyJhZnRlciI6IkFRSFR5cFc1NVlNZ2h1X1k0RldGbjJYQUdBMGY1YjFEWHh1YzZQcDdaYlROeFpEYVdiTnhHZk8yNkJlaFdSalJZMHF0NXQzbUw1NGVXcHhsODhncWZyVm90QSIsImRvYyI6IjI3ODM4OTUxNzMyNDA0MTkxIiwiaGFuZGxlIjoibmF0Z2VvIiwicGsiOiI3ODcxMzIifQ.l3oh0sXLTSB09YYzYGanBw",
    "hasMore": true,
    "count": 12
  },
  "meta": {
    "platform": "instagram",
    "endpoint": "instagram.userReels",
    "creditsCharged": 1,
    "cached": false,
    "cacheAgeSeconds": null,
    "durationMs": 1939,
    "requestId": "req_dwry80kdbev8rnirvqbr"
  }
}

Returns

Returns a list of Post in data.items.

Cost and behaviour

Credits

1 per live request, 0 on a cache hit

Cacheable

yes: cache_max_age accepts a cached copy

Batchable

yes: usable as a target in POST /v1/jobs/batch

Subscribable

yes: as often as every 3600 seconds, firing a webhook only on a change

Other Instagram endpoints

/v1/instagram/audio-reels Reels using a sound
/v1/instagram/comment-replies Replies under one comment
/v1/instagram/hashtag-posts Posts under a hashtag
/v1/instagram/highlight Stories inside a highlight
/v1/instagram/popular-search Top posts for a keyword
/v1/instagram/post Post or reel details
/v1/instagram/post-comments Comments on a post or reel
/v1/instagram/profile Profile details

All Instagram endpoints The unified schema

Contents

Site