> ## Documentation Index
> Fetch the complete documentation index at: https://docs.influship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Instagram Live Data

> Retrieve Instagram profiles and posts, and download their videos.

Retrieve Instagram profiles and posts, including downloadable video URLs. For stored posts, `GET /v1/posts` can include durable media URLs. Use raw endpoints when you need the source platform response; see [data freshness](/concepts/creators-vs-profiles).

| Before you start | Details |
| - | - |
| Auth | API key or OAuth; supported payment rails also available |
| Resource | Instagram username or post shortcode |
| Cost | 0.5 credits/profile; 1 credit/post with API-key/OAuth billing |
| Limits | Set `include_posts=true`; `post_limit` accepts 1–50, default 12; temporary URLs expire |

## Single video

Call `GET /v1/raw/instagram/post/{shortcode}` (1 credit, \$0.01). The response includes `video_url` (single best stream) and `video_versions[]` (multi-bitrate variants).

```bash theme={null}
SHORTCODE="CXY123abc"
curl -s "https://api.influship.com/v1/raw/instagram/post/$SHORTCODE" \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  | jq -r '.data.video_url' \
  | xargs -I{} wget -O "$SHORTCODE.mp4" "{}"
```

Use `video_versions[]` if you need a specific bitrate or resolution — each entry includes a `url` and a `type` field identifying the stream quality.

## All recent videos from a creator (bulk)

Call `GET /v1/raw/instagram/profile/{username}?include_posts=true` (0.5 credits, \$0.005). Set `post_limit` from 1–50 (default 12) to retrieve available recent posts, with `video_url` for each video post.

A profile request costs 0.5 credits and can include multiple recent posts. Individual post lookups cost 1 credit each.

```bash theme={null}
USERNAME="creator"
curl -s "https://api.influship.com/v1/raw/instagram/profile/$USERNAME?include_posts=true&post_limit=12" \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  | jq -r '.data.posts[] | select(.is_video) | "\(.shortcode)\t\(.video_url)"' \
  | while IFS=$'\t' read -r sc url; do
      wget -O "${sc}.mp4" "$url"
    done
```

## Carousel posts with videos

For carousel posts that contain video items, each slide is exposed in `carousel_items[]`. Filter by `is_video` to isolate the video items:

```bash theme={null}
SHORTCODE="CXY456def"
curl -s "https://api.influship.com/v1/raw/instagram/post/$SHORTCODE" \
  -H "X-API-Key: $INFLUSHIP_API_KEY" \
  | jq -r '.data.carousel_items[] | select(.is_video) | "\(.index)\t\(.video_url)"' \
  | while IFS=$'\t' read -r idx url; do
      wget -O "${SHORTCODE}_${idx}.mp4" "$url"
    done
```

## Request failures

Live profile and post retrieval share one request budget with recovery attempts. Recovery uses the remaining time in that budget; it does not start a fresh timeout window. Treat a timeout as an incomplete request. Retry temporary `503 service_unavailable` responses with bounded backoff and honor `Retry-After` when present. See the [SDK retry guidance](/sdks) for handling live-data errors.

## URL lifetime

`video_url` and `video_versions[].url` are signed Instagram CDN URLs valid for approximately 24 hours from the moment of the API call. Download promptly. If you need to retain videos long-term, store them on your own infrastructure — re-requesting the same shortcode after the URLs expire costs an additional credit.

## Cost summary

| Pattern | Endpoint | Credits | Cost |
| - | - | -: | -: |
| Single video | `GET /v1/raw/instagram/post/{shortcode}` | 1 | \$0.01 |
| Recent posts from one creator | `GET /v1/raw/instagram/profile/{username}?include_posts=true` | 0.5 | \$0.005 |
| Carousel (per post) | `GET /v1/raw/instagram/post/{shortcode}` | 1 | \$0.01 |

## Implementation advice

* **Prefer the profile endpoint for bulk work.** If you want the recent video content from a specific creator, one profile call is cheaper than calling the post endpoint per shortcode.
* **Download before storing the URL.** Don't cache the signed URL itself — it expires. Either download the file immediately or re-fetch the URL when you need it.
* **Check `is_video` before downloading.** Both profile `posts[]` and carousel `carousel_items[]` contain mixed photo and video items. Filtering on `is_video: true` avoids requesting video fields that aren't present on photo posts.

## Terms of service

Instagram's terms of service govern downloaded content. Use videos in accordance with applicable law and Instagram's ToS.

## Profile counts and omitted fields

`media_count` is the total profile media count, or `null` when unknown. Zero means an observed total of zero. `posts.length` counts only the posts returned by this request.

Raw Instagram profiles omit `highlight_reel_count`, `is_business`, and `is_professional`. Remove reads of these fields when updating an integration; their absence does not establish an account type or highlight count. These fields differ from stored profile lookups and TikTok responses.

When saving a profile response, update supplied fields and preserve previously known metadata for omitted fields.

`bio_links` contains available valid links. Unusable source entries are excluded during profile recovery, so an empty array does not establish that the creator has no links. Treat `external_url: null` as unavailable website data and preserve a previously known website when merging a recovered response.

A `502 upstream_contract_broken` response means the source response failed validation. Stop automatic retries and retain your last usable result. A query error or ambiguous empty response does not establish that a profile was deleted.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.