Instagram Highlight Items API

Instagram Highlight Items

Features

• Multi-highlight inputSubmit one or more numeric highlight IDs, with one upstream lookup made for each supplied identifier.
• Normalized Story item recordsReceive item IDs, public URLs, title or caption text, author identity, visible metrics, media metadata, and timestamps in one record shape.
• Source highlight attributionEach returned item retains the submitted highlight ID in extra.highlight_id so records from multiple Highlights remain distinguishable.

Parameters

How to Use

Submit known highlight IDs as an asynchronous task, poll its task ID, then read the saved normalized records with result cursor pagination.

1. Prepare one or more current numeric highlight IDs; when an ID is unknown, first collect Story Highlights by username and read extra.highlight_id from the returned container record.
2. POST highlight_ids to /v1/instagram/highlight-items.
3. Poll /v1/tasks/{task_id} until the status is succeeded or failed.
4. Read /v1/tasks/{task_id}?limit=50 and follow results.next_cursor while results.has_more is true.

# Replace the documented sample with a current highlight ID before running.
curl -X POST "https://api.socq.ai/v1/instagram/highlight-items" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"highlight_ids":["18067016518767507"]}'

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

Best Use Cases

• Saved Story content inventory: Organize returned item IDs, text, public URLs, media references, and timestamps into a reviewable inventory for known Highlights.
• Highlight media review: Inspect image or video URLs, thumbnails, dimensions, duration, captions, and author context for the Story items currently exposed by each Highlight.
• Cross-highlight comparison: Group records by extra.highlight_id and compare returned content types, publication times, authors, and visible metrics across selected Highlights.

Pro Tips

• When highlight IDs are unknown, call instagram/story-highlights by username first and use extra.highlight_id from successful results; this endpoint does not discover IDs from usernames.
• Remove duplicate IDs before submission because the collector performs an independent lookup for every supplied value.
• Do not add results_limit; each highlight ID yields the items available in its single upstream response.
• Use resource to distinguish highlight-items from story-highlights because both normalized record families use type story.
• Treat text, author fields, metrics, media, URLs, and timestamps as optional, and allow unavailable or removed Story items to produce no record.
• Follow results.next_cursor only to read additional stored task records; it does not continue collection from Instagram.

Related APIs