Instagram User Stories API

Endpoint

GET /v1/instagram/user/stories

Parameters

username

Instagram username, with or without leading @ (max 100 characters). Provide either username or url.

url

Instagram profile URL, e.g. https://instagram.com/natgeo (max 500 characters). Provide either username or url.

Response fields

stories

Array of the user's active stories, oldest first

title

Story title (format: @username on Instagram)

url

Direct link to the story

date

Publication date and time

date_timestamp

Publication date as a Unix timestamp

expires_at

Expiry date and time

expires_at_timestamp

Expiry as a Unix timestamp

author

Instagram username

author_id

Author's Instagram user ID

author_name

Author's display name

author_verified

Whether the author is verified

source

"Instagram"

domain

"instagram.com"

snippet

Story caption text (usually empty)

is_video

Whether the story is a video

media_type

"story"

media_id

Instagram media ID

thumbnail_url

Story image or video cover (temporary; valid ~6-24 hours)

video_url

Direct video URL for video stories, empty for images (temporary; valid ~6-24 hours)

video_duration

Video length in seconds (null for images)

width

Media width in pixels

height

Media height in pixels

location

Geotag: name, city, lat, lng (or null)

tagged_users

Users tagged in the story (username, full_name, user_id)

mentions

Usernames mentioned in the story

links

Link stickers (url, title)

audio

Audio track: type, title, artist, audio_id, duration_ms (null when none)

coauthors

Collaborators on the story (username, full_name, user_id, is_verified)

is_paid_partnership

Whether the story is a paid partnership

username

The requested username

count

Number of stories returned

Example Request

curl "https://apidirect.io/v1/instagram/user/stories?username=natgeo" \
  -H "X-API-Key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://apidirect.io/v1/instagram/user/stories",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "username": "natgeo"
    }
)
print(response.json())

Example Response

{
  "stories": [
    {
      "title": "@natgeo on Instagram",
      "url": "https://instagram.com/stories/natgeo/3976510169036109894/",
      "date": "2026-09-01 10:02:53",
      "date_timestamp": 1788256973,
      "expires_at": "2026-09-02 10:02:53",
      "expires_at_timestamp": 1788343373,
      "author": "natgeo",
      "author_id": "787132",
      "author_name": "National Geographic",
      "author_verified": true,
      "source": "Instagram",
      "domain": "instagram.com",
      "snippet": "",
      "is_video": false,
      "media_type": "story",
      "media_id": "3976510169036109894",
      "thumbnail_url": "https://scontent.cdninstagram.com/v/t51.82787-15/story.jpg",
      "video_url": "",
      "video_duration": null,
      "width": 750,
      "height": 1334,
      "location": null,
      "tagged_users": [],
      "mentions": [],
      "links": [
        {
          "url": "https://www.nationalgeographic.com/environment/article/super-el-nino-extreme-weather-climate",
          "title": "Visit Link"
        }
      ],
      "audio": null,
      "coauthors": [],
      "is_paid_partnership": false
    }
  ],
  "username": "natgeo",
  "count": 3
}

Frequently asked questions

How long are stories available?

24 hours from posting. Stories the user saved to their profile are available through the User Highlights endpoint.

Why is the stories array empty?

The account has no active stories, or it is private. Both return 200 with an empty array.

Do the media URLs expire?

Yes, after roughly 6-24 hours. Re-request the story when you need fresh links.

How does pricing work?

You only pay for successful requests. The Instagram User Stories API costs $0.006 per request. There are no monthly fees or commitments. You get 50 free requests per endpoint every month.

Do I need a credit card to start?

No. You can sign up and use the free tier (50 requests/endpoint/month) without adding a payment method. You only need to add a card when you want to exceed the free tier.

Are there rate limits?

Yes, there's a concurrency limit of 5 simultaneous requests per endpoint per user. If you need more, just get in touch.