User
View a list of a user's medias, following and followers
user_id- Integer ID of user, example1903424587
| Method | Return | Description |
|---|---|---|
| user_followers(user_id: str, amount: int = 0, order: Optional[FOLLOWERS_ORDER] = None) | Dict[str, UserShort] | Get dict of follower users (amount=0 - fetch all followers); order uses the private mobile followers endpoint |
| user_following(user_id: str, amount: int = 0) | Dict[str, UserShort] | Get dict of following users (amount=0 - fetch all) |
| iter_user_followers_v1(user_id: str, amount: int = 0, page_size: int = 200, order: Optional[FOLLOWERS_ORDER] = None) | AsyncIterator[UserShort] | Stream followers from the private/mobile API without building a full dict |
| iter_user_following_v1(user_id: str, amount: int = 0, page_size: int = 200) | AsyncIterator[UserShort] | Stream following users from the private/mobile API without building a full dict |
| search_followers(user_id: str, query: str) | List[UserShort] | Search by followers |
| search_following(user_id: str, query: str) | List[UserShort] | Search by following |
| user_info(user_id: str) | User | Get user info |
| user_info_by_username(username: str) | User | Get user info by username |
| user_follow(user_id: str) | bool | Follow user, or request to follow a private user |
| user_unfollow(user_id: str) | bool | Unfollow user |
| user_block(user_id: str, surface: UserBlockSurface = "profile") | bool | Block a user from a profile or Direct thread surface |
| user_unblock(user_id: str, surface: UserBlockSurface = "profile") | bool | Unblock a user from a profile or Direct thread surface |
| user_follow_requests(amount: int = 0) | List[UserShort] | Get pending incoming follow requests |
| user_follow_request_approve(user_id: str) | bool | Approve a pending incoming follow request |
| user_follow_request_decline(user_id: str) | bool | Decline a pending incoming follow request |
| user_follow_requests_approve(user_ids: List[str]) | Dict[str, bool] | Approve pending incoming follow requests |
| user_follow_requests_decline(user_ids: List[str]) | Dict[str, bool] | Decline pending incoming follow requests |
| user_id_from_username(username: str) | int | Get user_id by username |
| username_from_user_id(user_id: str) | str | Get username by user_id |
| user_report(user_id: str, reason: USER_REPORT_REASON = "spam") | bool | Report a user account. Currently supports the live-verified spam report flow |
| user_remove_follower(user_id: str) | bool | Remove your follower |
| mute_posts_from_follow(user_id: str) | bool | Mute posts from following user |
| unmute_posts_from_follow(user_id: str) | bool | Unmute posts from following user |
| mute_stories_from_follow(user_id: str) | bool | Mute stories from following user |
| enable_posts_notifications(user_id: str) | bool | Enable post notifications of user |
| disable_posts_notifications(user_id: str) | bool | Disable post notifications of user |
| enable_videos_notifications(user_id: str) | bool | Enable videos notifications of user |
| disable_videos_notifications(user_id: str) | bool | Disable videos notifications of user |
| enable_reels_notifications(user_id: str) | bool | Enable reels notifications of user |
| disable_reels_notifications(user_id: str) | bool | Disable reels notifications of user |
| enable_stories_notifications(user_id: str) | bool | Enable stories notifications of user |
| disable_stories_notifications(user_id: str) | bool | Disable stories notifications of user |
| close_friend_add(user_id: str) | bool | Add to Close Friends List |
| close_friend_remove(user_id: str) | bool | Remove from Close Friends List |
| user_suggested_profiles(user_id: str, expand_suggestion: bool = False) | dict | Suggested profiles ("Suggested for you") for a profile. Wraps chaining and, with expand_suggestion=True, returns the raw fetch_suggestion_details payload (items in current app responses) |
| address_book_link(contacts: List[AddressBookContact | dict], include: Sequence[str] | str = ("extra_display_name", "thumbnails")) | dict | Upload/link address book contacts and return Instagram's raw contact-based suggestions response |
| address_book_unlink() | dict | Disconnect the uploaded address book from the current account |
Option types
Follower sort orders are exposed as FOLLOWERS_ORDER = Literal["date_followed_latest", "date_followed_earliest"].
Pass None to keep Instagram's default follower order.
User block surfaces are exposed as UserBlockSurface = Literal["profile", "direct_thread_info"].
User report reasons are exposed as USER_REPORT_REASON = Literal["spam"].
| Type | Values | Used by |
|---|---|---|
FOLLOWERS_ORDER |
"date_followed_latest", "date_followed_earliest" |
user_followers(order=...), user_followers_v1(order=...), iter_user_followers_v1(order=...) |
UserBlockSurface |
"profile", "direct_thread_info" |
user_block(surface=...), user_unblock(surface=...) |
USER_REPORT_REASON |
"spam" |
user_report(reason=...) |
user_report(user_id, reason="spam") follows Instagram's current mobile FRX report flow for account spam reports and submits the report. reason uses USER_REPORT_REASON and currently supports "spam". This is a real account action; use it only for accounts you actually intend to report. Unsupported reasons raise ValueError until their FRX tag paths are captured and tested.
Low level methods:
| Method | Return | Description |
|---|---|---|
| user_followers_gql_chunk(user_id: str, max_amount: int = 0, end_cursor: str = None) | Tuple[List[UserShort], str] | Get user's followers information by Public Graphql API and end_cursor |
| user_followers_gql(user_id: str, amount: int = 0) | List[UserShort] | Get user's followers information by Public Graphql API |
| user_followers_v1_chunk(user_id: str, max_amount: int = 0, max_id: str = "", order: Optional[FOLLOWERS_ORDER] = None) | Tuple[List[UserShort], str] | Get user's followers information by Private Mobile API and max_id (cursor) |
| user_followers_v1(user_id: str, amount: int = 0, order: Optional[FOLLOWERS_ORDER] = None) | List[UserShort] | Get user's followers information by Private Mobile API |
| iter_user_followers_v1(user_id: str, amount: int = 0, page_size: int = 200, order: Optional[FOLLOWERS_ORDER] = None) | AsyncIterator[UserShort] | Stream followers page by page through user_followers_v1_chunk() |
| user_followers_private_gql_chunk(user_id: str, max_amount: int = 0, max_id: str = None, rank_token: str = None, order: Optional[FOLLOWERS_ORDER] = None) | Tuple[List[UserShort], str] | Get user's followers information by Private GraphQL API and max_id |
| user_followers_private_gql(user_id: str, amount: int = 0, rank_token: str = None, order: Optional[FOLLOWERS_ORDER] = None) | List[UserShort] | Get user's followers information by Private GraphQL API |
| user_following_v1(user_id: str, amount: int = 0) | List[UserShort] | Get user's following users information by Private Mobile API |
| iter_user_following_v1(user_id: str, amount: int = 0, page_size: int = 200) | AsyncIterator[UserShort] | Stream following users page by page through user_following_v1_chunk() |
| user_following_private_gql_chunk(user_id: str, max_amount: int = 0, max_id: str = None, rank_token: str = None, order: Optional[FOLLOWERS_ORDER] = None) | Tuple[List[UserShort], str] | Get user's following users information by Private GraphQL API and max_id |
| user_following_private_gql(user_id: str, amount: int = 0, rank_token: str = None, order: Optional[FOLLOWERS_ORDER] = None) | List[UserShort] | Get user's following users information by Private GraphQL API |
| user_following_gql(user_id: str, amount: int = 0) | List[UserShort] | Get user's following information by Public Graphql API |
| user_follow_requests_chunk(max_amount: int = 0, max_id: str = "") | Tuple[List[UserShort], str] | Get pending incoming follow requests by Private Mobile API and max_id |
| search_followers_v1(user_id: str, query: str) | List[UserShort] | Search by followers by Private Mobile API |
| search_following_v1(user_id: str, query: str) | List[UserShort] | Search by following by Private Mobile API |
| private_graphql_followers_list(user_id: str, rank_token: str, ..., order: Optional[FOLLOWERS_ORDER] = None) | dict | Raw private mobile GraphQL followers list. Supports date_followed_latest and date_followed_earliest |
| private_graphql_following_list(user_id: str, rank_token: str, ..., order: Optional[FOLLOWERS_ORDER] = None) | dict | Raw private mobile GraphQL following list. Accepts the mobile order option |
Use order="date_followed_latest" or order="date_followed_earliest" with FollowingList to request chronological sorting for your own following list. When you request another account’s list, Instagram may ignore both values and return the same viewer-ranked order. The raw and typed GraphQL helpers preserve the order returned by Instagram. See issue #2857.
user_follow() returns True only when it sends a new follow action and Instagram reports either an immediate follow or a new outgoing follow request for a private account. It returns False when the current account already follows the target or already has a pending outgoing follow request. Use user_friendship_v1() when you need to distinguish following from outgoing_request.
UserShort objects returned from private GraphQL follow-list payloads preserve selected v2-only fields when Instagram sends them: friendship_status, profile_pic_id, fbid_v2, interop_messaging_user_fbid, strong_id__, and raw account_badges. The legacy latest_reel_media property is also populated from Instagram's current 1llatest_reel_media key.
When authenticated, user_followers() and user_following() use the private mobile API and may restart through private GraphQL (FollowersList/FollowingList) for endpoint/schema failures or a limited followers response. They do not fall back to legacy public queries. Authorization, challenge, throttling, transport and programming errors propagate.
Example:
>>> [user.pk for user in (await cl.user_followers(cl.user_id)).values()]
[5563084402, 43848984510, 1498977320, ...]
>>> await cl.user_following(cl.user_id)
{
8530498223: UserShort(
pk=8530498223,
username="something",
full_name="Example description",
profile_pic_url=HttpUrl(
'https://instagram.frix7-1.fna.fbcdn.net/v/t5...9217617140_n.jpg',
scheme='https',
host='instagram.frix7-1.fna.fbcdn.net',
...
),
),
49114585: UserShort(
pk=49114585,
username='gx1000',
full_name='GX1000',
profile_pic_url=HttpUrl(
'https://scontent-hel3-1.cdninstagram.com/v/t51.2885-19/10388...jpg',
scheme='https',
host='scontent-hel3-1.cdninstagram.com',
...
)
),
...
}
>>> (await cl.user_info_by_username('example')).dict()
{'pk': 1903424587,
'username': 'example',
'full_name': 'Example Example',
'is_private': False,
'profile_pic_url': HttpUrl('https://scontent-hel3-1.cdninstagram.com/v/t51.2885-19/s150x150/123884060_803537687159702_2508263208740189974_n.jpg?...', scheme='https', host='scontent-hel3-1.cdninstagram.com', tld='com', host_type='domain', ...'),
'is_verified': False,
'media_count': 102,
'follower_count': 576,
'following_count': 538,
'biography': 'Engineer: Python, JavaScript, Erlang',
'external_url': HttpUrl('https://example.org/', scheme='https', host='example.org', tld='com', host_type='domain', path='/'),
'is_business': False}
Example: We go around the list of our followers and unfollow from them:
from aiograpi import Client
cl = Client()
await cl.login(USERNAME, PASSWORD)
followers = await cl.user_followers(cl.user_id)
for follower in followers.values():
await cl.user_unfollow(follower.pk)
Example: Stream large follow lists without storing the full result:
Both iterators yield each user ID once per invocation, keeping the first occurrence when pages overlap. amount limits unique users; 0 iterates until pagination ends. They retain seen user IDs in memory, while user objects can be processed incrementally. Deduplication preserves the order returned by Instagram and does not guarantee chronological ordering or a complete snapshot of a changing list.
async for follower in cl.iter_user_followers_v1(cl.user_id, amount=1000, page_size=100, order="date_followed_latest"):
print(follower.pk, follower.username)
async for user in cl.iter_user_following_v1(cl.user_id, amount=1000, page_size=100):
print(user.pk, user.username)
Example: Suggested profiles ("Suggested for you") for a target user:
from aiograpi import Client
from aiograpi.exceptions import InvalidTargetUser
cl = Client()
await cl.login(USERNAME, PASSWORD)
user_id = await cl.user_id_from_username("example")
try:
suggested = await cl.user_suggested_profiles(user_id)
# Expanded social-context fields (current app responses expose them under "items"):
detailed = await cl.user_suggested_profiles(user_id, expand_suggestion=True)
except InvalidTargetUser:
# Instagram refuses chaining for locked-down / private targets
suggested = {"users": []}
Public profile routing
The public branches of user_info(), user_info_by_username() and user_id_from_username() use modern profile GraphQL. user_info_gql(user_id) fetches the profile directly by ID. Private-first selection and caches are preserved; user_info_by_username_gql() remains an explicit legacy method. See public profile routing and remaining legacy queries for session requirements and migration limits.