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

Instagram

Instagram: users, posts, reels, stories, and comments. All endpoints are read-only GET requests and return public Instagram data — no account of your own is required.

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

Endpoints

Endpoint
Description
Pagination

Users

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

—

Posts & Reels

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/post/code/{code}

Get a single post by shortcode

—

Stories

GET /instagram/user/{id}/stories

Get a user's currently-active stories

—

Comments

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. This is the common entry point for the rest of the service — see Resolving a handle to a user ID below.

Request

Parameters

Parameter
Type
Required
Description

handle

string

Yes

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

Example

Response

Credit cost: dynamic, returned in pricing.creditsCharged.

Get User By Handle

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

Request

Parameters

Parameter
Type
Required
Description

handle

string

Yes

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

Example

Response

Credit cost: dynamic, returned in pricing.creditsCharged.

Get User By ID

Returns an Instagram user profile by numeric user ID.

Request

Parameters

Parameter
Type
Required
Description

id

string

Yes

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

Example

Response

Credit cost: dynamic, returned in pricing.creditsCharged.

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
Description

id

string

Yes

Numeric Instagram user ID, 1–100 characters

maxItems

integer

No

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

cursor

string

No

Pagination cursor from a previous response. Mutually exclusive with maxItems

Example

Response

Credit cost: dynamic, returned in pricing.creditsCharged. Cost scales with the number of posts returned, not the number of requests.

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
Description

id

string

Yes

Numeric Instagram user ID, 1–100 characters

maxItems

integer

No

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

cursor

string

No

Pagination cursor from a previous response. Mutually exclusive with maxItems

Example

Response

Credit cost: dynamic, returned in pricing.creditsCharged. Cost scales with the number of posts returned, not the number of requests.

Get User Reels

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

Request

Parameters

Parameter
Type
Required
Description

id

string

Yes

Numeric Instagram user ID, 1–100 characters

maxItems

integer

No

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

cursor

string

No

Pagination cursor from a previous response. Mutually exclusive with maxItems

Example

Response

Credit cost: dynamic, returned in pricing.creditsCharged. Cost scales with the number of reels returned, not the number of requests.

Get Post By Shortcode

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

Request

Parameters

Parameter
Type
Required
Description

code

string

Yes

Post shortcode, 1–100 characters (e.g. CzABCdef123)

Example

Response

Credit cost: dynamic, returned in pricing.creditsCharged.

Get User Stories

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

Request

Parameters

Parameter
Type
Required
Description

id

string

Yes

Numeric Instagram user ID, 1–100 characters

Example

Response

Credit cost: dynamic, returned in pricing.creditsCharged.

Get Post Comments

Returns comments on an Instagram post. Use cursor to paginate or maxItems for a one-shot bulk pull (mutually exclusive).

Request

Parameters

Parameter
Type
Required
Description

id

string

Yes

Numeric Instagram post ID, 1–100 characters

maxItems

integer

No

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

cursor

string

No

Pagination cursor from a previous response. Mutually exclusive with maxItems

Example

Response

Credit cost: dynamic, returned in pricing.creditsCharged. Cost scales with the number of comments returned, not the number of requests.

Object Schemas

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

City shown on profile, nullable

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

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

Tagged location, nullable

image

object

Image media data, nullable

video

object

Video media data, nullable

audio

object

Audio track data, nullable

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

Image media data, nullable

video

object

Video media data, nullable

audio

object

Audio track data, nullable

link

object

Attached link sticker data, nullable

comments

array

Comments left on the story

mentions

array

Mentioned accounts

hashtags

array

Tagged hashtags

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

Resolving a handle to a user ID

Every endpoint except the two handle-based lookups (GET /instagram/user/handle/{handle} and GET /instagram/userid/{handle}) requires a numeric user ID, not a handle. If you only have a handle:

  1. Call GET /instagram/userid/{handle} to resolve it to a numeric id and confirm isAvailable is true.

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

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

Pagination

  • List endpoints (posts, tagged posts, reels, comments) support cursor-based pagination: pass cursor from the previous response's pagination.cursor to get the next page, or use maxItems for a one-shot bulk pull instead. cursor and maxItems are mutually exclusive.

  • pagination.hasNextPage indicates whether more results are available.

  • The user and story endpoints (profile lookups, active stories, single post by shortcode) are not paginated — they always return the full result in one call.

Last updated