Instagram User Highlights API
The highlight reels pinned to a profile: title, cover, and how many stories each holds. Pass an id from here to /v1/instagram/highlight for the stories inside one. Highlights are the only Instagram stories that stay public indefinitely: live stories expire in 24 hours and are not served logged-out. **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
/v1/instagram/user-highlights| 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. |
Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).
curl "$API/v1/instagram/user-highlights?handle=natgeo&cache_max_age=7d" \
-H "x-api-key: $KEY"const query = new URLSearchParams({
handle: 'natgeo',
cache_max_age: '7d',
});
const response = await fetch(`${API}/v1/instagram/user-highlights?${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);import os, httpx
r = httpx.get(
f"{os.environ['API']}/v1/instagram/user-highlights",
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 , with raw removed and lists cut to two items. A live call returns current data.
{
"success": true,
"data": {
"items": [
{
"id": "highlight:18023864549864045",
"title": "BOTW 2027",
"thumbnailUrl": "https://scontent-hkg1-2.cdninstagram.com/v/t58.9792-6/859997535_2631174661043575_6410428937125336621_n.jpg?stp=dst-jpg_s150x150_tt6&_nc_cat=107&ccb=7-5&_nc_sid=acbce5&_nc_ohc=7LsZ-FnQ1lMQ7kNvwHNvjJp&_nc_oc=AdpZculowKsD5JGzGlAyFOXVc_I48OOwk6FJhv3qEhKU4Ikabuqh2QHgmsSdaBJntG0&_nc_zt=14&_nc_ht=scontent-hkg1-2.cdninstagram.com&_nc_gid=pLhSdCIf9c27tWHvTNbl1Q&_nc_ss=70a8c&oh=00_AQNMpk3NwORes-4ytXa5LVVgkvXTtsM8z8zlI18O6M_xyQ&oe=6ADA0AD9",
"mediaCount": null,
"url": "https://www.instagram.com/stories/highlights/18023864549864045/",
"ownerId": "787132",
"ownerHandle": "natgeo",
"createdAt": null
}
]
},
"meta": {
"platform": "instagram",
"endpoint": "instagram.userHighlights",
"creditsCharged": 1,
"cached": false,
"cacheAgeSeconds": null,
"durationMs": 1530,
"requestId": "req_oww1gdt3qgttuhaig81u"
}
}Returns
Returns a list of object in data.items.
Fields
| Field | Type | Present |
|---|---|---|
| id | string | always |
| title | string | null | always |
| thumbnailUrl | string | null | always |
| mediaCount | number | null | always |
| url | string | null | always |
| ownerId | string | null | always |
| ownerHandle | string | null | always |
| createdAt | string | null | always |
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