Instagram Highlight Stories API

Endpoint

GET /v1/instagram/highlight/stories

Parameters

highlight_id *

Highlight ID from the User Highlights endpoint, e.g. 17987606483520330, or a highlight URL like https://www.instagram.com/stories/highlights/17987606483520330/ (max 500 characters)

Response fields

highlight

The highlight

highlight_id

Highlight ID

title

Highlight title

media_count

Number of stories in the highlight

cover_url

Cover image URL (temporary; valid ~6-24 hours)

created_at

Creation date and time

created_at_timestamp

Creation date as a Unix timestamp

updated_at

Date and time a story was last added

updated_at_timestamp

Last-updated date as a Unix timestamp

is_pinned

Whether the highlight is pinned on the profile

url

Direct link to the highlight

author

Owner's Instagram username

author_id

Owner's Instagram user ID

stories

The stories in the highlight, 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

Always empty (highlight stories do not expire)

expires_at_timestamp

Always null (highlight stories do not expire)

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

count

Number of stories returned

Example Request

curl "https://apidirect.io/v1/instagram/highlight/stories?highlight_id=17987606483520330" \
  -H "X-API-Key: YOUR_API_KEY"

import requests

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

Example Response

{
  "highlight": {
    "highlight_id": "17987606483520330",
    "title": "Football 🏈",
    "media_count": 4,
    "cover_url": "https://scontent.cdninstagram.com/v/t51.82787-15/cover.jpg",
    "created_at": "2023-10-24 03:48:13",
    "created_at_timestamp": 1698114493,
    "updated_at": "2023-10-24 03:51:23",
    "updated_at_timestamp": 1698114683,
    "is_pinned": false,
    "url": "https://instagram.com/stories/highlights/17987606483520330/",
    "author": "mrbeast",
    "author_id": "2278169415"
  },
  "stories": [
    {
      "title": "@mrbeast on Instagram",
      "url": "https://instagram.com/stories/mrbeast/3219347044383400902/",
      "date": "2023-10-22 17:34:53",
      "date_timestamp": 1697996093,
      "expires_at": "",
      "expires_at_timestamp": null,
      "author": "mrbeast",
      "author_id": "2278169415",
      "author_name": "MrBeast",
      "author_verified": true,
      "source": "Instagram",
      "domain": "instagram.com",
      "snippet": "",
      "is_video": false,
      "media_type": "story",
      "media_id": "3219347044383400902",
      "thumbnail_url": "https://scontent.cdninstagram.com/v/t51.82787-15/story.jpg",
      "video_url": "",
      "video_duration": null,
      "width": 1284,
      "height": 2282,
      "location": null,
      "tagged_users": [],
      "mentions": [
        "buccaneers"
      ],
      "links": [],
      "audio": null,
      "coauthors": [],
      "is_paid_partnership": false
    }
  ],
  "count": 4
}

Frequently asked questions

Where do I get a highlight ID?

From the User Highlights endpoint. You can also pass the highlight URL directly.

Why is expires_at empty?

Highlight stories are saved permanently, so they have no expiry.

How does pricing work?

You only pay for successful requests. The Instagram Highlight 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.