Fetch a profile's stories

Fetch the currently-active stories of a public profile, by username or full profile URL. Each item comes with a direct, time-limited media link you can download from.

GET /v1/instagram/profile/stories

Media links expire

media_url is a short-lived CDN link. ListenX does not store any media — you get the direct link and should download it promptly (stories also expire ~24h after posting).

No active stories

A profile with no active stories (or a private account this service can't view) returns an empty items list with count: 0.

Query parameters

Parameter	Type	Default	Description
profile	string	—	Required. A username (nasa), @handle, or full profile URL (https://www.instagram.com/nasa/).
extract_text	boolean	false	When true, read on-image text from each story via OCR into items[].ocr_text. Adds latency.

Example

curl -G "$LISTENX_BASE/v1/instagram/profile/stories" \
  -H "X-API-Key: $LISTENX_KEY" \
  --data-urlencode 'profile=nasa'

With on-image text extraction (OCR):

curl -G "$LISTENX_BASE/v1/instagram/profile/stories" \
  -H "X-API-Key: $LISTENX_KEY" \
  --data-urlencode 'profile=nasa' \
  --data-urlencode 'extract_text=true'

Response

{
  "username": "nasa",
  "profile": {
    "id": "528817151",
    "username": "nasa",
    "full_name": "NASA",
    "is_verified": true,
    "profile_pic_url": "https://…"
  },
  "count": 4,
  "items": [
    {
      "id": "3995378102477387204",
      "type": "video",
      "taken_at": "2026-09-27T10:49:59+00:00",
      "expiring_at": "2026-09-28T10:49:59+00:00",
      "permalink": "https://www.instagram.com/stories/nasa/3995378102477387204/",
      "media_url": "https://instagram.fcdn.net/o1/v/t2/f2/m78/AQPT84…",
      "thumbnail_url": "https://…",
      "width": 1080,
      "height": 1920,
      "video_duration": 14.966,
      "text": "Launch day! Watch live at 2pm ET",
      "text_stickers": ["Launch day!", "Watch live at 2pm ET"],
      "hashtags": ["artemis", "moon"],
      "mentions": [
        { "id": "15904929129", "username": "spacex", "full_name": "SpaceX" }
      ],
      "location": {
        "id": "212988663",
        "name": "Kennedy Space Center",
        "address": "",
        "city": "Merritt Island, Florida",
        "lat": 28.5729,
        "lng": -80.6490
      },
      "locations": [
        {
          "id": "212988663",
          "name": "Kennedy Space Center",
          "address": "",
          "city": "Merritt Island, Florida",
          "lat": 28.5729,
          "lng": -80.6490
        }
      ],
      "links": ["https://www.nasa.gov/artemis"],
      "repost": false,
      "reposted_from": null,
      "ocr_text": "LAUNCH DAY WATCH LIVE 2PM ET"
    }
  ],
  "billing": {
    "endpoint": "instagram.stories",
    "units": 1,
    "unit_price": "0.010000",
    "amount": "0.010000",
    "balance_after": "97.220000",
    "request_id": "…"
  }
}

Fields

Field	Description
count	Number of active story items.
items[].type	image or video.
items[].media_url	Direct CDN link to download the full-resolution media. Expires.
items[].permalink	Canonical instagram.com/stories/<user>/<id>/ link.
items[].taken_at / expiring_at	When the story was posted / when it expires (UTC).
items[].text	Visible text on the story — overlay text, or the transcribed on-image text when no caption is set.
items[].text_stickers	Typed text overlays the poster added with the text tool.
items[].hashtags	Hashtag stickers added to the story (empty when none).
items[].mentions	Accounts tagged/mentioned on the story (empty when none).
items[].location / locations	The primary / all location stickers tagged on the story.
items[].links	Outbound link-sticker URLs on the story (empty when none).
items[].repost	true when the story re-shares another account's content.
items[].reposted_from	The original author's handle when repost is true, else null.
items[].ocr_text	Text read off the story image via OCR. null unless the request set extract_text=true.

Text and sticker fields (text, text_stickers, hashtags, mentions, location, links) are only populated when the poster added them; otherwise they come back as empty lists / null.

repost is true when the story reshares or credits another account's content — either a reshared feed/story post, or a story that @-mentions an account other than the owner (how reposted clips credit the original creator). reposted_from is the credited account (the full list is in mentions).

ocr_text is only present when you pass extract_text=true. It reads text rendered on the story image itself (useful when text is burned into the image rather than added as a sticker). OCR is best-effort — stylised or low-contrast text may come back partial — so treat it as a supplement to text / text_stickers, not a guarantee.

Billing

Billed per request (1 unit). See Billing.