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_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. Supports mobile order when accepted by Instagram |
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.
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:
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": []}