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

# Instagram

> Posts and reels from public Instagram profiles, plus profile details. scraper_type instagram and instagram_profile.

`instagram` collects the posts and reels of public Instagram accounts. One result is one post. For profile details
only, use [`instagram_profile`](#profile-details).

## Run it

```python Python theme={null}
import os

from gofetch import GoFetchClient

client = GoFetchClient(api_key=os.environ["GOFETCH_API_KEY"])

run = client.actor("instagram").call(run_input={"usernames": ["nasa"], "limit": 20})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    if item.get("type") in ("Image", "Video", "Sidecar"):
        print(item["timestamp"], item["url"], item["likesCount"], item["commentsCount"])
```

```bash cURL theme={null}
curl https://go-fetch.io/api/v1/jobs/create/ \
  -H "X-API-Key: $GOFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scraper_type": "instagram", "config": {"usernames": ["nasa"], "limit": 20}}'
```

## Inputs

Send `usernames`, `directUrls`, or both, in `config`. Both are collected, and an account given in both, in any
case, is collected and billed once.

| Field | Type | Default | What it does |
| - | - | - | - |
| `usernames` | list of text | | Accounts to collect, with or without `@`. Not case-sensitive; usernames come back in lower case. |
| `directUrls` | list of URLs | | Profile links such as `https://www.instagram.com/nasa/`. Each row's `inputUrl` gives your link back as you sent it. |
| `limit` | integer | `50` | Posts per profile, from 0 to 1,000,000: no profile returns, or is billed for, more post rows than this. `0` collects every post. Posts another account authored are left out by default and use none of it; with `includeCollabPosts`, the ones returned count toward it. |
| `onlyPostsNewerThan` | date (`YYYY-MM-DD`) | | Only posts published on or after this date (from 00:00 UTC). Not in the future. |
| `includeCollabPosts` | true / false | `false` | Also return posts another account authored that appear on this profile (collaborations). |
| `includeReelsTabPosts` | true / false | `true` without a recent date filter, `false` with one | Also read the profile's Reels tab, to find reels that are not on its grid. |
| `maxTotalChargeUsd` | number | | A spending cap, split across the accounts as a per-account `maxPosts` that never exceeds your `limit`. See [Billing](https://docs.go-fetch.io/billing.md#cap-a-job-with-maxtotalchargeusd). |

> [!NOTE]
>
> Only profiles are supported. `hashtags` are refused with `400`: hashtag search isn't supported. So is a link or
> name that points at a post, reel, story or other page (`/p/`, `/reel/`, `/reels/`, `/tv/`, `/stories/`,
> `/explore/`, `/accounts/`, `/direct/`), with a `400` naming the field: send post links to
> [Instagram comments](https://docs.go-fetch.io/scrapers/instagram-comments.md) for their comments. `limit: 0` is how to collect every post.
> Field names are case-sensitive. An unknown field is ignored rather than refused, and named in a warning in the
> job's log.

These inputs are accepted for compatibility but have no effect. A value other than the one shown adds a warning to
the job's log:

* `include_reels` (`true`): reels always come back.
* `include_igtv` (`false`) and `include_stories` (`false`): IGTV videos and stories are not collected.
* `resultsType` (`"posts"`).
* `addParentData`, `enhanceUserSearchWithFacebookPage` and `isUserTaggedFeedURL` (`false`).

A date filter within the last 29 days makes the job a recent crawl, which is billed at its own rate; see
[Billing](https://docs.go-fetch.io/billing.md#rates).

## Output

The job returns one `profile_info` row per profile, then one row per post. Both are billed as results. Real rows
from a job for @nasa:

```json theme={null}
[
  {
    "type": "profile_info",
    "username": "nasa",
    "userId": "528817151",
    "actualPostCount": 4965,
    "discoveredPostCount": 424,
    "verified": true
  },
  {
    "id": "4004634989362489982",
    "type": "Video",
    "shortCode": "DeTUk4sDSp-",
    "url": "https://www.instagram.com/p/DeTUk4sDSp-/",
    "timestamp": "2026-10-10T15:15:02.000Z",
    "caption": "POV: you're watching the Earth set\n\nWe just released hundreds of new images and hours of new audio from our Artemis II mission around the Moon this spring. Check out our link in bio for the Artemis II Preliminary Lunar Science Report.\n\n#NASA #ArtemisII #Artemis",
    "alt": null,
    "hashtags": [
      "NASA",
      "ArtemisII",
      "Artemis"
    ],
    "mentions": [],
    "sponsors": [
      "nasaartemis",
      "nasasolarsystem"
    ],
    "likesCount": 673404,
    "commentsCount": 6628,
    "videoViewCount": 2873840,
    "displayUrl": "https://scontent-lax3-1.cdninstagram.com/v/t51.82787-15/842191580_18656578867049152_4200499629839780998_n.jpg?stp=dst-jpg_e15_tt6&_nc_ht=scontent-lax3-1.cdninstagram.com&_nc_cat=104&_nc_oc=Q6cZ2gGoRI1QAnv1CqyldSRVHqK5EzgZq2faBTwFSnAxrUwDt4a7p5emBNZzZDDGRqe0INU&_nc_ohc=3YKBrXihQzAQ7kNvwHYDKbp&_nc_gid=np6N_9IYLVACZz6S6AsAdw&edm=APU89FABAAAA&ccb=7-5&oh=00_AQO7MpAki4qf1xKjOV0Hg5IZqWTUANFELdIKrk0269vleg&oe=6AD612D7&_nc_sid=bc0c2c",
    "images": [
      "https://scontent-lax3-1.cdninstagram.com/v/t51.82787-15/842191580_18656578867049152_4200499629839780998_n.jpg?stp=dst-jpg_e15_tt6&_nc_ht=scontent-lax3-1.cdninstagram.com&_nc_cat=104&_nc_oc=Q6cZ2gGoRI1QAnv1CqyldSRVHqK5EzgZq2faBTwFSnAxrUwDt4a7p5emBNZzZDDGRqe0INU&_nc_ohc=3YKBrXihQzAQ7kNvwHYDKbp&_nc_gid=np6N_9IYLVACZz6S6AsAdw&edm=APU89FABAAAA&ccb=7-5&oh=00_AQO7MpAki4qf1xKjOV0Hg5IZqWTUANFELdIKrk0269vleg&oe=6AD612D7&_nc_sid=bc0c2c"
    ],
    "videoUrl": "https://scontent-lax7-1.cdninstagram.com/o1/v/t2/f2/m86/AQNUvreb47JFAC3mKM7kF_weYHzhiVF-MfERm99CfyBTok0ezeRdbVW8cH5NXn4mxO8gVi6j1GQ2RU9i4ByvKCLVPHdDruUpsCKYDQI.mp4?_nc_cat=105&_nc_sid=5e9851&_nc_ht=scontent-lax7-1.cdninstagram.com&_nc_ohc=N5jcpICv8_oQ7kNvwE5UA8w&efg=eyJ2ZW5jb2RlX3RhZyI6Inhwdl9wcm9ncmVzc2l2ZS5JTlNUQUdSQU0uQ0xJUFMuQzMuNzE4LmRhc2hfYmFzZWxpbmVfMV92MSIsInhwdl9hc3NldF9pZCI6MTg2NTY0MjU5NjMwNDkxNTIsImFzc2V0X2FnZV9kYXlzIjo0LCJ2aV91c2VjYXNlX2lkIjoxMDA5OSwiZHVyYXRpb25fcyI6NDMsInVybGdlbl9zb3VyY2UiOiJ3d3cifQ%3D%3D&ccb=17-1&vs=968afb625a8cd52f&_nc_vs=HBksFQIYUmlnX3hwdl9yZWVsc19wZXJtYW5lbnRfc3JfcHJvZC8wMzJERDAzMDk4RkU0QkU4QUE1NkY2RUNFMDMzMjkxNl92aWRlb19kYXNoaW5pdC5tcDQVAALIARIAFQIYUWlnX3hwdl9wbGFjZW1lbnRfcGVybWFuZW50X3YyLzIwQzg2MTY2NUNENjRBMTFBRkE3RTM4ODA0ODlCQTk4X2F1ZGlvX2Rhc2hpbml0Lm1wNBUCAsgBEgAoABgAGwKIB3VzZV9vaWwBMRJwcm9ncmVzc2l2ZV9yZWNpcGUBMRUAACaAw_Kk9fqjQhUCKAJDMywXQEXmZmZmZmYYEmRhc2hfYmFzZWxpbmVfMV92MREAdf4HZeadAQA&_nc_gid=np6N_9IYLVACZz6S6AsAdw&_nc_ss=7a22e&_nc_zt=28&oh=00_AQPoRb6hngyRYzZFWVcN7guv-NL5ShhSGemBRwnzTSx5sA&oe=6AD23C56",
    "videoDuration": null,
    "dimensionsHeight": 1918,
    "dimensionsWidth": 1080,
    "paidPartnership": false,
    "isSponsored": false,
    "inputUrl": "https://www.instagram.com/nasa",
    "ownerUsername": "nasa",
    "ownerVerified": true,
    "coauthorUsernames": [
      "nasasolarsystem",
      "nasaartemis"
    ],
    "isCollab": true,
    "username": "nasa"
  }
]
```

The `profile_info` row above is shortened to its documented fields. It also echoes the job's settings, such as
`maxPosts` and `onlyPostsNewerThan`.

### Post fields

| Field | Type | What it holds |
| - | - | - |
| `id` | text | Instagram's id for the post. |
| `type` | text | `Image`, `Video` or `Sidecar` (a carousel). |
| `shortCode` | text | The code in the post's link. |
| `url` | URL | Link to the post. |
| `timestamp` | date-time | When it was posted (ISO 8601, UTC). |
| `caption` | text | The post's text; `""` when there is none. |
| `alt` | text or null | Instagram's accessibility caption, when it has one. |
| `hashtags` | list of text | Hashtags in the caption, without `#`. |
| `mentions` | list of text | Accounts mentioned in the caption, without `@`. |
| `sponsors` | list of text | Business or verified accounts tagged in the post. Not a paid-partnership flag. |
| `likesCount` | integer or null | Likes. |
| `commentsCount` | integer or null | Comments. |
| `videoViewCount` | integer | Views for videos; `0` when unknown or not a video. |
| `displayUrl` | URL | The main image. |
| `images` | list of URLs | Every image, including each slide of a carousel. |
| `videoUrl` | URL or null | The video file. |
| `videoDuration` | number or null | Video length, when Instagram gives it. |
| `dimensionsHeight`, `dimensionsWidth` | integer | Size in pixels; `0` when unknown. |
| `paidPartnership` | true / false | Instagram labels the post a paid partnership. |
| `isSponsored` | true / false | Instagram's sponsored flag. |
| `ownerUsername` | text | The post's author. On a collaboration this can differ from `username`. |
| `ownerVerified` | true / false / null | Whether the author is verified; null when unknown. |
| `coauthorUsernames` | list of text | Collaborators on the post. |
| `isCollab` | true / false | The post has collaborators. |
| `username` | text | The profile whose feed returned the post. |
| `inputUrl` | URL | The profile you asked for. |

Media links point at Instagram's servers and expire after a while; download what you need to keep.

### Profile summary row (`type: "profile_info"`)

| Field | What it holds |
| - | - |
| `username`, `userId` | The profile and its Instagram id. |
| `actualPostCount` | Posts the profile shows. |
| `discoveredPostCount` | Posts found for this job. |
| `verified` | Whether the account is verified. |

### Other rows

| Row | Looks like | Billed |
| - | - | - |
| A profile we can't resolve | `type: "profile_error"`, with `username`, `originalUrl`, `error`, `errorDetails` and `isRestrictedProfile: true` | No |
| A profile Instagram refused to crawl | No `type`; `error: "Blocked by Instagram"`, `isRestrictedProfile: false`, `restriction` and `restrictionReason`. A later run may succeed | No |
| A restricted profile | No `type`; `error: "Restricted profile"`, `isRestrictedProfile: true`, `restriction` and `restrictionReason` | No |
| A private account | `type: "Profile"`, `isPrivate: true`, with profile counts and no posts. Also listed in `restrictions` with `restriction: "private"` | No |
| A post that could not be read | `type: "post_error"`, with `shortcode`, `url` and `error` | No |

A profile we can't resolve returns one `profile_error` row at \$0. `/results/` `total` includes it and the other
status rows, so it can exceed `items_scraped`, which counts billed rows. Page with `total`.

## What logged-out means here

**You get:** posts and reels from public accounts, with captions, counts and media links as a signed-out visitor
sees them, and author fields on every post.

**Not available:**

* Private accounts.
* Accounts Instagram age-restricts for signed-out visitors.
* Accounts Instagram shows only after login.
* Anything only a signed-in user can see.

`restriction` says which of these stopped a profile: `private`, `age_gate`, `login_wall` or `unavailable`.
`restrictionReason` explains it in words. Re-running the job does not change `private` or `age_gate`. A
"Blocked by Instagram" row carries `restriction: "unknown"`: none of these applied, and a later run may succeed.

## Completeness

A completed job reports what happened to each profile in `scraper_metadata`
([Jobs and results](https://docs.go-fetch.io/jobs-and-results.md#is-it-complete)):

| Key | What it says |
| - | - |
| `profiles_scraped`, `profiles_failed` | Profiles collected, and profiles that failed or were cut short. |
| `completeness.complete` | `false` when any profile stopped before the end of what you asked for. |
| `completeness.partial_profiles` | Up to 50 profiles that stopped early, each with `username` and `stop_reason`. |
| `restrictions` | Profiles Instagram withheld: `username`, `restriction`, `restrictionReason`. |
| `targets_failed` | Profiles that returned nothing: `target`, `reason`, `detail` (for reading, not parsing) and `retriable`. |

A profile is in `restrictions` or in `targets_failed`, never both. If you collect every post of a profile (no date
filter) and a profile returns nothing after every attempt, the whole job fails.

## Profile details

`instagram_profile` returns one row per account with its details and up to 12 recent posts. It takes the same
`usernames` and `directUrls`, and bills one result per profile row it returns. A handle sent twice, in any case, is
collected and billed once.

```python Python theme={null}
import os

from gofetch import GoFetchClient

client = GoFetchClient(api_key=os.environ["GOFETCH_API_KEY"])

run = client.actor("instagram_profile").call(run_input={"usernames": ["nasa", "natgeo"]})

for profile in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(profile["username"], profile["followersCount"], profile["postsCount"])
```

```bash cURL theme={null}
curl https://go-fetch.io/api/v1/jobs/create/ \
  -H "X-API-Key: $GOFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scraper_type": "instagram_profile", "config": {"usernames": ["nasa", "natgeo"]}}'
```

A real row, for @nasa:

```json theme={null}
[
  {
    "id": "528817151",
    "username": "nasa",
    "url": "https://www.instagram.com/nasa",
    "fullName": "NASA",
    "biography": "Making the seemingly impossible, possible. ✨",
    "followersCount": 104368095,
    "followsCount": 90,
    "postsCount": 4965,
    "private": false,
    "verified": true,
    "country": "United States",
    "isBusinessAccount": true,
    "businessCategoryName": "Government Agencies",
    "profilePicUrl": "https://scontent-dfw5-2.cdninstagram.com/v/t51.2885-19/29090066_159271188110124_1152068159029641216_n.jpg?stp=dst-jpg_e0_s150x150_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLmRqYW5nby4xMDgwLmMyIn0&_nc_ht=scontent-dfw5-2.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2gHk02-Nuy6TQVsIXehJpoufIWzIkHaKk5RlYHZiC_eOGrzVQa2g60xC3O1N8MHO27A&_nc_ohc=Ogn7DgkblhgQ7kNvwH4V9kU&_nc_gid=U98Y7x6w_195IlERZG5p1w&edm=AOQ1c0wBAAAA&ccb=7-5&oh=00_AQOPqEhXIgLCcrkjWs_O3HiEjgrAMCR2cOWTXs2NronAwg&oe=6AD63E69&_nc_sid=8b3546",
    "profilePicUrlHD": "https://scontent-dfw5-2.cdninstagram.com/v/t51.2885-19/29090066_159271188110124_1152068159029641216_n.jpg?stp=dst-jpg_s320x320_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLmRqYW5nby4xMDgwLmMyIn0&_nc_ht=scontent-dfw5-2.cdninstagram.com&_nc_cat=1&_nc_oc=Q6cZ2gHk02-Nuy6TQVsIXehJpoufIWzIkHaKk5RlYHZiC_eOGrzVQa2g60xC3O1N8MHO27A&_nc_ohc=Ogn7DgkblhgQ7kNvwH4V9kU&_nc_gid=U98Y7x6w_195IlERZG5p1w&edm=AOQ1c0wBAAAA&ccb=7-5&oh=00_AQM8RuuGPV1ctjW2dB-o0pYVLmZsdr_1hpoVqiSdTm6mGQ&oe=6AD63E69&_nc_sid=8b3546",
    "highlightReelCount": 6,
    "hasChannel": false,
    "pronouns": [],
    "categoryName": null,
    "isProfessionalAccount": true,
    "igtvVideoCount": 171,
    "joinedRecently": false,
    "businessEmail": null,
    "businessPhoneNumber": null,
    "businessAddress": {
      "city_name": null,
      "city_id": null,
      "latitude": null,
      "longitude": null,
      "street_address": null,
      "zip_code": null
    },
    "transparencyLabel": null,
    "externalUrls": [
      {
        "title": "NASA.gov Homepage",
        "url": "https://www.nasa.gov"
      },
      {
        "title": "MAX POWER",
        "url": "https://www.nasa.gov/maxpower"
      },
      {
        "title": "Roman Space Telescope Blog",
        "url": "https://science.nasa.gov/blogs/roman/"
      },
      {
        "title": "How to Watch NASA Livestreams",
        "url": "http://nasa.gov/ways-to-watch"
      },
      {
        "title": "Artemis II Preliminary Lunar Science Report",
        "url": "https://science.nasa.gov/feature/artemis-ii-preliminary-lunar-science-report/"
      }
    ],
    "relatedProfiles": [
      {
        "id": "1389225126",
        "full_name": "National Geographic Your Shot",
        "is_private": false,
        "is_verified": true,
        "profile_pic_url": "https://scontent-dfw5-2.cdninstagram.com/v/t51.82787-19/682869933_18586755823041127_7038301864805341036_n.jpg?stp=dst-jpg_e0_s150x150_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLmRqYW5nby40MDAuYzIifQ&_nc_ht=scontent-dfw5-2.cdninstagram.com&_nc_cat=107&_nc_oc=Q6cZ2gHk02-Nuy6TQVsIXehJpoufIWzIkHaKk5RlYHZiC_eOGrzVQa2g60xC3O1N8MHO27A&_nc_ohc=O2FtYogDYxsQ7kNvwGz69bI&_nc_gid=U98Y7x6w_195IlERZG5p1w&edm=AOQ1c0wBAAAA&ccb=7-5&oh=00_AQMGya9R5CktHiubliajgl55cw2jkDm7HYJfrCkwShp9yw&oe=6AD61D16&_nc_sid=8b3546",
        "username": "natgeoyourshot"
      },
      {
        "id": "3443079229",
        "full_name": "JAXA（宇宙航空研究開発機構）",
        "is_private": false,
        "is_verified": true,
        "profile_pic_url": "https://scontent-dfw5-1.cdninstagram.com/v/t51.2885-19/67697812_1146045952450062_1671753193186394112_n.jpg?stp=dst-jpg_e0_s150x150_tt6&efg=eyJ2ZW5jb2RlX3RhZyI6InByb2ZpbGVfcGljLmRqYW5nby4yMDAuYzIifQ&_nc_ht=scontent-dfw5-1.cdninstagram.com&_nc_cat=106&_nc_oc=Q6cZ2gHk02-Nuy6TQVsIXehJpoufIWzIkHaKk5RlYHZiC_eOGrzVQa2g60xC3O1N8MHO27A&_nc_ohc=DlJEBbB7TTEQ7kNvwFhTDXk&_nc_gid=U98Y7x6w_195IlERZG5p1w&edm=AOQ1c0wBAAAA&ccb=7-5&oh=00_AQOh1XEmx8MyZuhQktWPdFvb6_qQlqhh8If8cyY9NVRtyw&oe=6AD629F6&_nc_sid=8b3546",
        "username": "jaxajp"
      }
    ],
    "latestPosts": [
      {
        "id": "4004634989362489982",
        "shortCode": "DeTUk4sDSp-",
        "caption": "POV: you're watching the Earth set\n\nWe just released hundreds of new images and hours of new audio from our Artemis II mission around the Moon this spring. Check out our link in bio for the Artemis II Preliminary Lunar Science Report.\n\n#NASA #ArtemisII #Artemis",
        "url": "https://www.instagram.com/p/DeTUk4sDSp-/",
        "displayUrl": "https://scontent-dfw5-2.cdninstagram.com/v/t51.82787-15/842191580_18656578867049152_4200499629839780998_n.jpg?stp=dst-jpg_e15_tt6&_nc_ht=scontent-dfw5-2.cdninstagram.com&_nc_cat=104&_nc_oc=Q6cZ2gHk02-Nuy6TQVsIXehJpoufIWzIkHaKk5RlYHZiC_eOGrzVQa2g60xC3O1N8MHO27A&_nc_ohc=3YKBrXihQzAQ7kNvwGc8nHa&_nc_gid=U98Y7x6w_195IlERZG5p1w&edm=AOQ1c0wBAAAA&ccb=7-5&oh=00_AQPCBnjU42rshoAAY4jeGF8_G1EWdYEjltgQc9J0DHP9Gw&oe=6AD612D7&_nc_sid=8b3546",
        "likesCount": 673408,
        "commentsCount": 6628,
        "timestamp": "2026-10-10T15:15:02.000Z"
      }
    ],
    "inputUrl": "https://www.instagram.com/nasa/",
    "scrapedAt": "2026-10-15T04:34:25.636Z"
  }
]
```

Lists are shortened in this example: `latestPosts` holds up to 12 posts and `relatedProfiles` up to 50 accounts.

| Field | What it holds |
| - | - |
| `id`, `username`, `url` | The account. |
| `fullName`, `biography` | Display name and bio. |
| `followersCount`, `followsCount`, `postsCount` | Followers, accounts followed, posts. |
| `verified`, `private` | Badges. A returned profile row is always public. |
| `isBusinessAccount`, `isProfessionalAccount`, `businessCategoryName`, `categoryName` | Account kind and category. |
| `country` | The country most admins of the account's linked Facebook Page are in, when at least half are; otherwise null. |
| `externalUrls` | Links in the bio, each with `title` and `url`. |
| `profilePicUrl`, `profilePicUrlHD` | Profile picture links. |
| `highlightReelCount`, `igtvVideoCount`, `hasChannel`, `joinedRecently`, `pronouns`, `transparencyLabel` | As Instagram shows them. |
| `businessEmail`, `businessPhoneNumber`, `businessAddress` | Business contact details, when Instagram shows them to signed-out visitors. |
| `latestPosts` | Up to 12 recent posts with `id`, `shortCode`, `caption`, `url`, `displayUrl`, `likesCount`, `commentsCount`, `timestamp`. |
| `relatedProfiles` | Accounts Instagram suggests alongside this one. |
| `inputUrl`, `scrapedAt` | What you asked for, and when it was collected. |

A profile that can't be found returns `{"error": "Page not found", "username", "url", "scrapedAt"}`; a private one
returns the same shape with `"error": "Restricted profile"`. Neither costs anything. A private profile is also listed
in `scraper_metadata.restrictions` with `restriction: "private"`.


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