Instagram Live - API Cheat Sheet

Reading duration: 12 mins

A concise, technical cheat sheet covering Instagram Live APIs, including how to detect live broadcasts, pull playback URLs, record streams, and collect comments, likes, and viewer counts.

Quick overview

• Goal: detect a user going live, pull stream URLs, and record while collecting comments, likes, and viewer count.
• Core concept: every live has a broadcast_id. Use it to query info, heartbeat, comments, likes, and replay data.
• Most calls require an authenticated mobile/web session. Keep cookies, csrftoken, and uuid valid.

Endpoints seen

Notes

• like_count must be in 1..5 or or the mixin raises ValueError occurs.
• broadcast_status values observed in info: active, interrupted, stopped, hard_stop.

Typical live record flow

1. Discover a live
2. Given a user numeric user_id , call user_broadcast(user_id).
3. If present, extract broadcast_id.
4. Get playback URLs
5. Call broadcast_info(broadcast_id) to retrieve fields like dash_playback_url (MPD) and rtmp_playback_url.
6. Start recording
7. Prefer dash_playback_url for adaptive MPEG-DASH.
8. Maintain session
9. Poll broadcast_heartbeat_and_viewercount(broadcast_id) every 5 to 10 seconds to keep the session fresh and track viewer_count.
10. Ingest chat and likes
11. Loop broadcast_comments(broadcast_id, last_comment_ts) and persist the largest created_at as the next last_comment_ts.
12. Periodically query broadcast_like_count(broadcast_id, like_ts) and advance like_ts .
13. Detect end of stream
14. broadcast_info or heartbeat will stop returning active. Close capture and finalize file.
15. Replay data (optional)
16. For post-live, use replay_broadcast_comments and replay_broadcast_likes with starting_offset to reconstruct engagement alongside VOD.

Minimal example pseudocode

user_id = ...
 
broadcast = api.user_broadcast(user_id)
if not broadcast:
    return  # not live
 
bid = str(broadcast["id"])  # broadcast_id
info = api.broadcast_info(bid)
mpd = info.get("dash_playback_url")
 
# start ffmpeg recording in a subprocess
start_ffmpeg(mpd, out_path)
 
last_comment_ts = 0
like_ts = 0
 
while is_running():
    # heartbeat + viewer count
    hb = api.broadcast_heartbeat_and_viewercount(bid)
 
    # comments
    comments = api.broadcast_comments(bid, last_comment_ts)
    for c in comments.get("comments", []):
        save_comment(c)
        last_comment_ts = max(last_comment_ts, c.get("created_at", 0))
 
    # likes
    likes = api.broadcast_like_count(bid, like_ts)
    like_ts = likes.get("like_ts", like_ts)
 
    # status check
    info = api.broadcast_info(bid)
    if info.get("broadcast_status") != "active":
        break
 
    sleep(7)
 
stop_ffmpeg()

Example broadcast_info data

{
  "status": "ok",
  "broadcast_status": "active",
  "media_id": "123...",
  "cover_frame_url": "https://...jpg",
  "broadcast_owner": {
    "username": "abc",
    "pk": 123456789,
    "is_verified": true,
    "is_private": false
  },
  "dash_playback_url": "https://.../something.mpd",
  "rtmp_playback_url": "rtmp://.../live-hd/...",
  "id": 178591123456789,
  "viewer_count": 9000.0
}

Error handling

• 403 → bad/expired auth. Refresh session.
• 404 → comments/likes unavailable (broadcast ended). Use replay endpoints.
• Heartbeat requires _csrftoken and _uuid even with unsigned=True.

Recommended reads