Instagram Story Highlights API

Instagram Story Highlights

Features

• Multi-profile Highlight inventorySubmit one or more Instagram usernames to list the public Story Highlight containers exposed for each account while retaining owner context.
• Container identity and contextReceive normalized Highlight IDs, titles, URLs, owner identity, directly exposed media, timestamps, public counts, and reported item totals.
• Item-level handoffUse extra.highlight_id to retain the container relationship and pass numeric Highlight IDs into item-level collection workflows.

Parameters

How to Use

Submit public account usernames as an asynchronous task, poll its task ID, then read normalized Highlight containers with result cursor pagination.

1. Prepare one or more public Instagram usernames as handles rather than profile URLs.
2. POST usernames to /v1/instagram/story-highlights.
3. Poll /v1/tasks/{task_id} until the status is succeeded or failed.
4. Read data.results.items and follow results.next_cursor while results.has_more is true.

curl -X POST "https://api.socq.ai/v1/instagram/story-highlights" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["instagram"]}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Best Use Cases

• Public profile category inventory: Organize Highlight titles, owner identity, URLs, and media counts into an inventory of the saved Story categories visible on a profile.
• Cross-account Highlight comparison: Compare container titles, reported item totals, media references, and available timestamps across submitted public usernames.
• Story collection selection: Use extra.highlight_id with titles and media_count to select numeric Highlight containers for subsequent item-level retrieval.

Pro Tips

• Normalize handles before submission by removing leading @ characters and de-duplicating the resulting usernames, because profile URLs are not converted into handles.
• Expect one Highlight-list request per username with no results_limit or provider continuation, so the available container list determines the records collected for each account.
• Use task-result next_cursor only to page through saved normalized records; it does not request another page of Highlights from Instagram.
• Pass only present numeric extra.highlight_id values to instagram/highlight-items when individual Story frames are required.
• Treat empty results as a possible no-Highlight or unavailable-profile outcome, and omit assumptions about optional media, metrics, URLs, and timestamps.

Related APIs