Social Fetch
Get API key
Instagram hub

Instagram profile posts API

Page a creator's public Instagram feed by handle — mixed media types, captions, shortcodes, and engagement — in the shared Social Fetch JSON envelope.

GET /v1/instagram/profiles/{handle}/posts

1 credit base. With `hostMedia`, +2 credits per hosted asset (up to 24 assets, 49 credits max).

Try in playgroundFull API docs

About this endpoint

`GET /v1/instagram/profiles/{handle}/posts` lists the public profile feed by username (with or without `@`). On a completed call, branch on `data.lookupStatus` (`found`, `private`, or `not_found`), then read `data.posts` and `data.page`. Each row can include id, shortcode, `mediaType` (`image`, `video`, `sidecar`, or `unknown`), caption, `createdAt` (ISO-8601), public URL, display/thumbnail/video URLs when present, like and comment counts, `playCount` for video, dimensions, and `taggedUsers`. When `data.page.hasMore` is true, pass `data.page.nextCursor` as the opaque `cursor` query param. Bill from `meta.creditsCharged`.

`displayUrl`, `thumbnailUrl`, and `videoUrl` are source-platform CDN links when Instagram exposes them. They can expire or be rejected outside the original retrieval context and are not SocialFetch-hosted assets. Syntactically unusable values (for example bare paths with no signature query) are omitted.

For SocialFetch-hosted copies on this list page, pass `hostMedia=true`. SocialFetch stores up to 24 assets for 90 days and returns time-limited delivery URLs in each post's `hostedMedia` array (+2 credits per successfully stored asset; failures are reported per asset and not charged). Source CDN fields stay unchanged. For a single known post URL, `GET /v1/instagram/posts?downloadMedia=true` returns provider-hosted URLs in `downloads` (not SocialFetch-owned storage).

This route is the mixed feed. The Reels tab alone is `GET /v1/instagram/profiles/{handle}/reels`. One known `/p/…` or `/reel/…` URL is `GET /v1/instagram/posts`. Resolve the profile card first with `GET /v1/instagram/profiles/{handle}` when you need identity and status before spending on feed pages.

Instagram profile posts API FAQ

How do I list Instagram feed posts for a profile via API?

Call `GET /v1/instagram/profiles/{handle}/posts` with your Social Fetch API key (`x-api-key`) and the Instagram username in the path. Read `data.lookupStatus`, then `data.posts` and `data.page`. See the API docs for parameters and examples.

How much does the Instagram profile posts endpoint cost?

1 credit per successful list page by default. With `hostMedia`, +2 credits per hosted asset (up to 24 assets, 49 credits max). Always bill from `meta.creditsCharged` on the response.

What media types appear in Instagram profile posts?

Each feed item carries `mediaType`: `image`, `video`, `sidecar` (carousel), or `unknown`. That is how you tell stills from albums and in-feed video without opening every URL. Reels-tab-only paging is a different route.

How does pagination work on Instagram profile posts?

Each response includes `data.page.nextCursor` and `data.page.hasMore`. When `hasMore` is true, pass `nextCursor` as the `cursor` query param on the next request. The cursor is opaque.

What fields are in each Instagram feed post?

Items can include id, shortcode, mediaType, caption, createdAt (ISO-8601), public URL, display and thumbnail URLs, video URL when available, likeCount, commentCount, playCount for video, dimensions, and taggedUsers when Instagram exposes them. Source CDN media URLs are transient — do not treat them as durable embeds.

Can I embed Instagram profile-post image URLs in my own HTML?

Not from the source CDN fields. `displayUrl`, `thumbnailUrl`, and `videoUrl` are Instagram links that can expire or fail with signature errors outside the fetch context. For SocialFetch-hosted copies on a feed page, call the same route with `hostMedia=true` and use `hostedMedia[].url` (valid until `expiresAt`; objects are retained up to 90 days). For a single known post URL, `GET /v1/instagram/posts?downloadMedia=true` returns provider-hosted URLs in `downloads`.

How does hostMedia pricing work on Instagram profile posts?

The list lookup is 1 credit. With `hostMedia`, +2 credits per hosted asset (up to 24 assets, 49 credits max per page). Failed assets are listed under `hostedMedia` with `status: failed` and are not surcharged.

When should I use profile posts instead of profile Reels?

Use this route when you need the public grid as Instagram shows it (images, sidecars, and in-feed video together). Use `GET /v1/instagram/profiles/{handle}/reels` when the job is short-form only and you want the Reels tab. Use `GET /v1/instagram/posts` when you already have one media URL.

What happens for private or missing Instagram accounts?

Branch on `data.lookupStatus`. Private handles resolve as `private`; unknown handles as `not_found`. Do not invent a feed. Keep `meta.requestId` if you need support on a failed list call.

Do I need Instagram Graph API access to list a feed?

No. Social Fetch returns publicly visible feed data for enrichment-style lookups. Meta's Instagram Graph API is for accounts you manage or that grant your app access — not arbitrary public creator timelines.

Other Instagram endpoints