Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Instagram

The Pullbay Instagram API provides programmatic access to public Instagram profile, post, reel, story, and comment data. Resolve handles to user IDs, pull a profile, list a user's posts/tagged posts/reels, read active stories, fetch a single post by shortcode, or pull comments on a post — all without scraping or owning an Instagram account of your own.

Base URL: https://api.pullbay.com

Overview

The Instagram service lets you:

  • Resolve a handle (@username) to Instagram's internal numeric user ID

  • Look up a full user profile by handle or by numeric ID

  • List a user's posts, posts they're tagged in, and reels (cursor-paginated)

  • Fetch a user's currently-active stories

  • Fetch a single post by its shortcode (the code in an instagram.com/p/{code}/ URL)

  • Fetch comments on a post by the post's internal ID (cursor-paginated)

All endpoints are read-only GET requests against public Instagram data — no account of your own is required. This service uses three distinct identifier types that are not interchangeable: handle (the @username, passed without the @), id (Instagram's internal numeric ID for a user, post, or comment), and code (a post's shortcode, the segment after /p/ in a post URL). Always check which one a given endpoint expects.

Common Use Cases

Influencer Vetting — Pull a creator's profile (follower count, post count, verification status) before negotiating a sponsorship, and check their recent posts for content fit and engagement levels.

Engagement Tracking — Poll a brand or creator account's posts and reels on a schedule to track likeCount and commentCount trends over time.

Campaign Monitoring — Fetch posts a brand account is tagged in to see how a hashtag or partnership campaign is performing across other accounts.

Comment Sentiment Analysis — Pull comments on a post and feed the message field into your own sentiment or moderation pipeline.

Story Archiving — Capture a user's active stories before they expire (24 hours after posting) for compliance, reporting, or content-repurposing workflows.

Endpoints

Endpoint
Description
Pagination

GET /instagram/userid/{handle}

Resolve a handle to a numeric user ID

—

GET /instagram/user/handle/{handle}

Get a user profile by handle

—

GET /instagram/user/{id}

Get a user profile by numeric ID

—

GET /instagram/user/{id}/posts

Get posts published by a user

Cursor / maxItems

GET /instagram/user/{id}/posts/tagged

Get posts a user is tagged in

Cursor / maxItems

GET /instagram/user/{id}/reels

Get reels published by a user

Cursor / maxItems

GET /instagram/user/{id}/stories

Get a user's currently-active stories

—

GET /instagram/post/code/{code}

Get a single post by shortcode

—

GET /instagram/post/{id}/comments

Get comments on a post

Cursor / maxItems

Resolve User ID

Returns whether a handle is available and, if it exists, the resolved Instagram user ID.

Request

Parameters

Parameter
Type
Required
Default
Description

handle

string (path)

Yes

—

Instagram handle, without @, 1–100 characters (e.g. instagram)

Example

Response

Response Schema

Field
Type
Description

data

array

Array containing a single User ID lookup object

pricing.creditsCharged

number

Credits charged for this request

Credit cost: charged dynamically per request; the exact amount is always returned in pricing.creditsCharged. No published flat rate — read the figure from the response.

Get User By Handle

Returns an Instagram user profile by handle (without @).

Request

Parameters

Parameter
Type
Required
Default
Description

handle

string (path)

Yes

—

Instagram handle, without @, 1–100 characters (e.g. instagram)

Example

Response

Response Schema

Field
Type
Description

data

array

Array containing a single User object

pricing.creditsCharged

number

Credits charged for this request

Credit cost: dynamic, returned in pricing.creditsCharged. No published flat rate.

Get User By ID

Returns an Instagram user profile by numeric user ID.

Request

Parameters

Parameter
Type
Required
Default
Description

id

string (path)

Yes

—

Numeric Instagram user ID, 1–100 characters (e.g. 25025320)

Example

Response

Response Schema

Field
Type
Description

data

array

Array containing a single User object

pricing.creditsCharged

number

Credits charged for this request

Credit cost: dynamic, returned in pricing.creditsCharged. No published flat rate.

Get User Posts

Returns posts published by an Instagram user. Use cursor to paginate or maxItems for a one-shot bulk pull (mutually exclusive).

Request

Parameters

Parameter
Type
Required
Default
Description

id

string (path)

Yes

—

Numeric Instagram user ID, 1–100 characters

maxItems

integer (query)

No

—

One-shot bulk pull, 1–200 results. Mutually exclusive with cursor

cursor

string (query)

No

—

Pagination cursor from a previous response. Mutually exclusive with maxItems

Example

Response

Response Schema

Field
Type
Description

data

array

Array of Post objects

pagination.hasNextPage

boolean, nullable

Whether another page is available

pagination.cursor

string, nullable

Cursor to pass as cursor on the next request

pagination.page / pagination.offset

nullable

Unused by this endpoint — always null here

pricing.creditsCharged

number

Credits charged for this request

Credit cost: dynamic, returned in pricing.creditsCharged. No published flat rate — read the figure from each response.

Get User Tagged Posts

Returns posts where the Instagram user is tagged. Use cursor to paginate or maxItems for a one-shot bulk pull (mutually exclusive).

Request

Parameters

Parameter
Type
Required
Default
Description

id

string (path)

Yes

—

Numeric Instagram user ID, 1–100 characters

maxItems

integer (query)

No

—

One-shot bulk pull, 1–200 results. Mutually exclusive with cursor

cursor

string (query)

No

—

Pagination cursor from a previous response. Mutually exclusive with maxItems

Example

Response

Response Schema

Field
Type
Description

data

array

Array of Post objects

pagination.hasNextPage

boolean, nullable

Whether another page is available

pagination.cursor

string, nullable

Cursor to pass as cursor on the next request

pagination.page / pagination.offset

nullable

Unused by this endpoint — always null here

pricing.creditsCharged

number

Credits charged for this request

Credit cost: dynamic, returned in pricing.creditsCharged. No published flat rate.

Get User Reels

Returns reels published by an Instagram user. Use cursor to paginate or maxItems for a one-shot bulk pull (mutually exclusive). Reels are returned using the same Post object schema as the posts endpoints — there is no separate "reel" schema.

Request

Parameters

Parameter
Type
Required
Default
Description

id

string (path)

Yes

—

Numeric Instagram user ID, 1–100 characters

maxItems

integer (query)

No

—

One-shot bulk pull, 1–200 results. Mutually exclusive with cursor

cursor

string (query)

No

—

Pagination cursor from a previous response. Mutually exclusive with maxItems

Example

Response

Response Schema

Field
Type
Description

data

array

Array of Post objects (returned with type: "reel")

pagination.hasNextPage

boolean, nullable

Whether another page is available

pagination.cursor

string, nullable

Cursor to pass as cursor on the next request

pagination.page / pagination.offset

nullable

Unused by this endpoint — always null here

pricing.creditsCharged

number

Credits charged for this request

Credit cost: dynamic, returned in pricing.creditsCharged. No published flat rate.

Get User Stories

Returns the user's currently-active Instagram stories. Not paginated — stories expire 24 hours after posting, so the full active set is always returned in one call.

Request

Parameters

Parameter
Type
Required
Default
Description

id

string (path)

Yes

—

Numeric Instagram user ID, 1–100 characters

Example

Response

Response Schema

Field
Type
Description

data

array

Array of Story objects

pricing.creditsCharged

number

Credits charged for this request

Credit cost: dynamic, returned in pricing.creditsCharged. No published flat rate.

Get Post By Shortcode

Returns a single Instagram post by its shortcode (the segment after /p/ in the post's URL).

Request

Parameters

Parameter
Type
Required
Default
Description

code

string (path)

Yes

—

Post shortcode, 1–100 characters (e.g. CzABCdef123, the code in instagram.com/p/CzABCdef123/)

Example

Response

Response Schema

Field
Type
Description

data

array

Array containing a single Post object

pricing.creditsCharged

number

Credits charged for this request

Credit cost: dynamic, returned in pricing.creditsCharged. No published flat rate.

Get Post Comments

Returns comments on an Instagram post. Use cursor to paginate or maxItems for a one-shot bulk pull (mutually exclusive). Takes the post's internal numeric id, not its shortcode.

Request

Parameters

Parameter
Type
Required
Default
Description

id

string (path)

Yes

—

Numeric Instagram post ID, 1–100 characters (not the post's shortcode)

maxItems

integer (query)

No

—

One-shot bulk pull, 1–500 results. Mutually exclusive with cursor

cursor

string (query)

No

—

Pagination cursor from a previous response. Mutually exclusive with maxItems

Example

Response

Response Schema

Field
Type
Description

data

array

Array of Comment objects

pagination.hasNextPage

boolean, nullable

Whether another page is available

pagination.cursor

string, nullable

Cursor to pass as cursor on the next request

pagination.page / pagination.offset

nullable

Unused by this endpoint — always null here

pricing.creditsCharged

number

Credits charged for this request

Credit cost: dynamic, returned in pricing.creditsCharged. No published flat rate.

Errors

All non-2xx responses share the same envelope:

Status
Meaning

400

Bad request — missing/invalid parameters

402

Insufficient credits

404

User, post, or story not found

Object Schema

User ID lookup object

Field
Type
Description

isAvailable

boolean

Whether the handle exists/is in use

handle

string

The handle that was looked up

id

string

Numeric Instagram user ID. Present only when isAvailable is true

User object

Field
Type
Description

type

string

Always user

isAvailable

boolean

Whether the profile is available

id

string

Numeric Instagram user ID

username

string

Handle, without @

fullName

string

Display name

biography

string

Bio text

profilePicUrl

string

Profile picture URL

website

string

Link in bio

category

string

Business/category label (e.g. App page)

cityName

string, nullable

City shown on profile

isPrivate

boolean

Whether the account is private

isVerified

boolean

Whether the account has a verified badge

isBusiness

boolean

Whether the account is a business account

hasVideos

boolean

Whether the account has published videos

hasGuides

boolean

Whether the account has published guides

postCount

integer

Total post count

followerCount

integer

Follower count

followingCount

integer

Following count

totalReelsCount

integer

Total reel count

bioLinks

array

Links shown in the bio

Post owner object

Lightweight user reference embedded in posts and stories.

Field
Type
Description

id

string

Numeric Instagram user ID

username

string

Handle, without @

fullName

string

Display name

profilePicUrl

string

Profile picture URL

isVerified

boolean

Whether the account has a verified badge

isPrivate

boolean

Whether the account is private

Post object

Used for posts, tagged posts, and reels — reels are returned with type: "reel" but share this same schema; there is no separate reel object.

Field
Type
Description

type

string

photo / video / carousel / reel

id

string

Numeric post ID

code

string

Shortcode (the segment after /p/ in the URL)

url

string

Permalink to the post

caption

string

Caption text

createdAt

integer

Unix timestamp (seconds) the post was published

likeCount

integer

Like count

commentCount

integer

Comment count

isAvailable

boolean

Whether the post is still available

isCarousel

boolean

Whether the post is a multi-media carousel

isVideo

boolean

Whether the post is a video

isPinned

boolean

Whether the post is pinned to the profile

isPaidPartnership

boolean

Whether the post is a paid partnership

isLikeAndViewCountsDisabled

boolean

Whether like/view counts are hidden

owner

object

Post owner object

coowners

array

Additional tagged collaborators, each a post owner object

location

object, nullable

Tagged location

image

object, nullable

Image media data

video

object, nullable

Video media data

audio

object, nullable

Audio track data

carouselMedia

array

Per-slide media for carousel posts

Comment object

Field
Type
Description

type

string

Always comment

id

string

Comment ID

userId

string

Numeric ID of the commenter

message

string

Comment text

createdAt

string (date-time)

When the comment was posted

likeCount

integer

Like count

replyCount

integer

Reply count

isRanked

boolean

Whether the comment is algorithmically ranked/pinned

user

object

Commenter reference (id, username, fullName, profilePicUrl, isPrivate, isVerified)

Story object

Field
Type
Description

type

string

photo / video

id

string

Story ID

code

string

Shortcode

createdAt

integer

Unix timestamp (seconds) the story was posted

expiringAt

integer

Unix timestamp (seconds) the story expires

duration

number

Duration in seconds

hasAudio

boolean

Whether the story has audio

hasTranslation

boolean

Whether translated text is available

canReshare

boolean

Whether the story can be reshared

canReply

boolean

Whether replies are allowed

isVideo

boolean

Whether the story is a video

owner

object

Post owner object

coowners

array

Additional tagged collaborators, each a post owner object

image

object, nullable

Image media data

video

object, nullable

Video media data

audio

object, nullable

Audio track data

link

object, nullable

Attached link sticker data

comments

array

Comments left on the story

mentions

array

Mentioned accounts

hashtags

array

Tagged hashtags

Finding User IDs and Handles

This service uses three distinct identifiers — keep them separate:

  • handle: the @username shown on a profile, passed without the @ (e.g. instagram for @instagram). Used only by GET /instagram/userid/{handle} and GET /instagram/user/handle/{handle}.

  • id: Instagram's internal numeric ID for a user, post, or comment. Required by every other endpoint in this service (posts, tagged posts, reels, stories, and post comments all key off a numeric id, not a handle or shortcode).

  • code: a post's shortcode — the segment after /p/ in a post's URL (e.g. CzABCdef123 in https://www.instagram.com/p/CzABCdef123/). Used only by GET /instagram/post/code/{code}.

1

If you only have a handle and need a numeric user id

Call GET /instagram/userid/{handle} to resolve the handle and confirm isAvailable is true. The response's id field is the numeric user ID.

2

Use that id for the user endpoints

Use that id for the posts, tagged posts, reels, and stories endpoints (/instagram/user/{id}/...).

If you need the full profile anyway, GET /instagram/user/handle/{handle} returns both the profile and the numeric id in a single call, saving a round trip.

A post's id (needed for the comments endpoint) is not the same as its code (shortcode). If you only have a post's shortcode, call GET /instagram/post/code/{code} first — the response's id field is the numeric post ID to use with GET /instagram/post/{id}/comments.

Python Example

This example resolves a handle to a user ID, then paginates through that user's posts using cursor:

Each request is billed independently, with the charged amount reported in that response's pricing.creditsCharged — there's no separate "fetch everything in one call" endpoint, so a multi-page pull like this makes one request per page.

FAQ

What's the difference between handle, id, and code?

handle is the @username (without the @), used only to resolve or look up a profile. id is Instagram's internal numeric identifier for a user, post, or comment, and is required by every other endpoint. code is a post's shortcode from its URL, used only to fetch a post by GET /instagram/post/code/{code}. They are not interchangeable — passing a handle where an id is expected (or vice versa) will not resolve.

How do I get a numeric user ID if I only have a handle?

Call GET /instagram/userid/{handle} and read the id field from the response, or call GET /instagram/user/handle/{handle} if you also want the full profile in the same request.

How do I get a post's numeric ID if I only have its shortcode?

Call GET /instagram/post/code/{code}. The returned Post object includes the post's numeric id, which you then use with GET /instagram/post/{id}/comments.

Are reels returned with a different schema than posts?

No. Reels use the same Post object schema as regular posts and tagged posts; the type field is set to reel (or video) to distinguish them.

Why don't stories support pagination?

Instagram stories expire 24 hours after posting, so the active set is always small enough to return in a single call. There is no cursor or maxItems parameter on the stories endpoint.

What's the credit cost per request?

It's dynamic — every response includes pricing.creditsCharged with the exact amount for that call. There's no fixed published rate per endpoint or per result.

Next Steps

  • API Integration Guide — integrate the Pullbay API into your backend application.

  • n8n Integration Guide — set up automated workflows using n8n with no coding required.

  • Services Overview — explore all available Pullbay services.

PreviousGoogle Search
NextReddit

Last updated