Skip to main content

Instagram stories and highlights via API

· 3 min read
GetSocialAPI
Product documentation and integration guides

Stories are where the daily attention lives — and highlights turn that ephemeral layer into a permanent archive the account curates itself. Both are one call each, and they compose into a pipeline.

Active stories​

GET /v1/ig/user/stories/{user_id}

The stories endpoint returns the currently live tray: images, videos, timestamps, and for video items the view and reaction counters the account itself can see. No pagination — the tray is small by nature (24h lifetime, max 100 items).

from getsocialapi import Client

ig = Client(api_key="gsa_live_...").instagram

stories = ig.user_stories(user_id="25025320")  # items[] with taken_at, media urls
for s in stories.get("items", []):
    print(s["taken_at"], s.get("media_type"))

Highlights: the curated archive​

GET /v1/ig/user/highlights/{user_id}          # tray: ids + titles
GET /v1/ig/highlight/stories/{highlight_id}   # stories inside one highlight

The highlights tray lists the account's highlight reels — id, title, cover media. Each reel unfolds through highlight stories:

tray = ig.user_highlights(user_id="25025320")
for h in tray.get("tray", []):
    reel = ig.highlight_stories(h["id"].replace("highlight:", ""))
    print(h.get("title"), "->", len(reel.get("items", [])), "stories")

Note the highlight: prefix some trays carry on ids — strip it before the second call (the SDK does this for you).

Why highlights matter more than they look​

Highlights are the only Instagram surface where the account itself performs permanent editorial selection. The tray order, titles, and what got promoted from stories to highlight — that combination is a free, self-reported content strategy:

  • Product catalogs — shops keep catalogs as highlights; the tray is the catalog structure.
  • Link-in-bio analytics — link stickers inside highlight stories are permanent CTAs; extracting them gives a real conversion surface inventory.
  • Compliance archiving — regulated industries must archive ephemeral marketing; highlights capture what the account chose to keep, stories what existed.

The daily pipeline​

  1. Poll stories for target accounts (they live 24h — cadence matters).
  2. Diff against your store; save new items with taken_at.
  3. On tray changes, pull the affected highlight and link its stories.
  4. Enrich with the profile card for follower context.

Two endpoints, one id quirk, no pagination to get wrong. Start tracking on getsocialapi.com — 100 free calls.

Build with GetSocialAPI​

Explore Instagram API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.