Instagram Structures¶

Posts¶

class instaloader.Post(context: InstaloaderContext, node: Dict[str, Any], owner_profile: Profile | None = None)¶

Structure containing information about an Instagram post.

Created by methods Profile.get_posts(), Instaloader.get_hashtag_posts(), Instaloader.get_feed_posts() and Profile.get_saved_posts(), which return iterators of Posts:

L = Instaloader()
for post in L.get_hashtag_posts(HASHTAG):
    L.download_post(post, target='#'+HASHTAG)

Might also be created with:

post = Post.from_shortcode(L.context, SHORTCODE)

This class unifies access to the properties associated with a post. It implements == and is hashable.

Parameters:

context – Instaloader.context used for additional queries if neccessary..
node – Node structure, as returned by Instagram.
owner_profile – The Profile of the owner, if already known at creation.

property accessibility_caption: str | None¶: Accessibility caption of the post, if available.

New in version 4.9.

property caption: str | None¶: Caption.

property caption_hashtags: List[str]¶: List of all lowercased hashtags (without preceeding #) that occur in the Post’s caption.

property caption_mentions: List[str]¶: List of all lowercased profiles that are mentioned in the Post’s caption, without preceeding @.

property comments: int¶: Comment count including answers

property date: datetime¶: Synonym to date_utc

property date_local: datetime¶: Timestamp when the post was created (local time zone).

Changed in version 4.9: Return timezone aware datetime object.

property date_utc: datetime¶: Timestamp when the post was created (UTC).

classmethod from_iphone_struct(context: InstaloaderContext, media: Dict[str, Any])¶: Create a post from a given iphone_struct.

New in version 4.9.

classmethod from_mediaid(context: InstaloaderContext, mediaid: int)¶: Create a post object from a given mediaid

classmethod from_shortcode(context: InstaloaderContext, shortcode: str)¶: Create a post object from a given shortcode

get_comments() → Iterable[PostComment]¶

Iterate over all comments of the post.

Each comment is represented by a PostComment NamedTuple with fields text (string), created_at (datetime), id (int), owner (Profile) and answers (Iterator [PostCommentAnswer]) if available.

Changed in version 4.7: Change return type to Iterable.

get_is_videos() → List[bool]¶: Return a list containing the is_video property for each media in the post.

New in version 4.7.

get_likes() → Iterator[Profile]¶: Iterate over all likes of the post. A Profile instance of each likee is yielded.

Changed in version 4.5.4: Require being logged in (as required by Instagram).

get_sidecar_nodes(start=0, end=-1) → Iterator[PostSidecarNode]¶: Sidecar nodes of a Post with typename==GraphSidecar.

Changed in version 4.6: Added parameters start and end to specify a slice of sidecar media.

property is_pinned: bool¶: Used to return True if this Post has been pinned by at least one user, now likely returns always false.

property is_sponsored: bool¶: Whether Post is a sponsored post, equivalent to non-empty Post.sponsor_users().

New in version 4.4.

property is_video: bool¶: True if the Post is a video.

property likes: int¶: Likes count

property location: PostLocation | None¶: If the Post has a location, returns PostLocation NamedTuple with fields ‘id’, ‘lat’ and ‘lng’ and ‘name’.

Changed in version 4.2.9: Require being logged in (as required by Instagram), return None if not logged-in.

property mediacount: int¶: The number of media in a sidecar Post, or 1 if the Post it not a sidecar.

New in version 4.6.

property mediaid: int¶: The mediaid is a decimal representation of the media shortcode.

static mediaid_to_shortcode(mediaid: int) → str¶

property owner_id: int¶: The ID of the Post’s owner.

property owner_profile: Profile¶: Profile instance of the Post’s owner.

property owner_username: str¶: The Post’s lowercase owner name.

property pcaption: str¶: Printable caption, useful as a format specifier for –filename-pattern.

New in version 4.2.6.

property profile: str¶: Synonym to owner_username

property shortcode: str¶: Media shortcode. URL of the post is instagram.com/p/<shortcode>/.

static shortcode_to_mediaid(code: str) → int¶

property sponsor_users: List[Profile]¶: The Post’s sponsors.

New in version 4.4.

static supported_graphql_types() → List[str]¶: The values of __typename fields that the Post class can handle.

property tagged_users: List[str]¶: List of all lowercased users that are tagged in the Post.

property title: str | None¶: Title of post

property typename: str¶: Type of post, GraphImage, GraphVideo or GraphSidecar

property url: str¶: URL of the picture / video thumbnail of the post

property video_duration: float | None¶: Duration of the video in seconds, or None.

New in version 4.2.6.

property video_url: str | None¶: URL of the video, or None.

property video_view_count: int | None¶: View count of the video, or None.

New in version 4.2.6.

property viewer_has_liked: bool | None¶: Whether the viewer has liked the post, or None if not logged in.

Additionally, the following trivial structures are defined:

class instaloader.PostSidecarNode(is_video: bool, display_url: str, video_url: str)¶

Item of a Sidecar Post.

display_url: str¶: URL of image or video thumbnail.

is_video: bool¶: Whether this node is a video.

video_url: str¶: URL of video or None.

class instaloader.PostComment(context: InstaloaderContext, node: Dict[str, Any], answers: Iterator[PostCommentAnswer], post: Post)¶

property answers: Iterator[PostCommentAnswer]¶: Iterator which yields all PostCommentAnswer for the comment.

property created_at_utc: datetime¶: datetime when comment was created (UTC).

classmethod from_iphone_struct(context: InstaloaderContext, media: Dict[str, Any], answers: Iterator[PostCommentAnswer], post: Post)¶

property id: int¶: ID number of comment.

property likes: Iterable[Profile]¶: Iterate over all likes of a comment. A Profile instance of each like is yielded.

New in version 4.11.

property likes_count¶: Number of likes on comment.

property owner: Profile¶: Owner Profile of the comment.

property text¶: Comment text.

class instaloader.PostCommentAnswer(id, created_at_utc, text, owner, likes_count)¶

created_at_utc: datetime¶: datetime when comment was created (UTC).

id: int¶: ID number of comment.

likes_count: int¶: Number of likes on comment.

owner: Profile¶: Owner Profile of the comment.

text: str¶: Comment text.

class instaloader.PostLocation(id, name, slug, has_public_page, lat, lng)¶

has_public_page: bool | None¶: Whether location has a public page.

id: int¶: ID number of location.

lat: float | None¶: Latitude (float or None).

lng: float | None¶: Longitude (float or None).

name: str¶: Location name.

slug: str¶: URL friendly variant of location name.

User Stories¶

class instaloader.Story(context: InstaloaderContext, node: Dict[str, Any])¶

Structure representing a user story with its associated items.

Provides methods for accessing story properties, as well as Story.get_items() to request associated StoryItem nodes. Stories are returned by Instaloader.get_stories().

With a logged-in Instaloader instance L, you may download all your visible user stories with:

for story in L.get_stories():
    # story is a Story object
    for item in story.get_items():
        # item is a StoryItem object
        L.download_storyitem(item, ':stories')

This class implements == and is hashable.

Parameters:

context – InstaloaderContext instance used for additional queries if necessary.
node – Dictionary containing the available information of the story as returned by Instagram.

get_items() → Iterator[StoryItem]¶: Retrieve all items from a story.

property itemcount: int¶: Count of items associated with the Story instance.

property last_seen_local: datetime | None¶: Timestamp of the most recent StoryItem that has been watched or None (local time zone).

property last_seen_utc: datetime | None¶: Timestamp of the most recent StoryItem that has been watched or None (UTC).

property latest_media_local: datetime¶: Timestamp when the last item of the story was created (local time zone).

property latest_media_utc: datetime¶: Timestamp when the last item of the story was created (UTC).

property owner_id: int¶: The story owner’s ID.

property owner_profile: Profile¶: Profile instance of the story owner.

property owner_username: str¶: The story owner’s lowercase username.

property unique_id: str | int¶: This ID only equals amongst Story instances which have the same owner and the same set of StoryItem. For all other Story instances this ID is different.

class instaloader.StoryItem(context: InstaloaderContext, node: Dict[str, Any], owner_profile: Profile | None = None)¶

Structure containing information about a user story item i.e. image or video.

Created by method Story.get_items(). This class implements == and is hashable.

Parameters:

context – InstaloaderContext instance used for additional queries if necessary.
node – Dictionary containing the available information of the story item.
owner_profile – Profile instance representing the story owner.

property caption: str | None¶: Caption.

New in version 4.10.

property caption_hashtags: List[str]¶: List of all lowercased hashtags (without preceeding #) that occur in the StoryItem’s caption.

New in version 4.10.

property caption_mentions: List[str]¶: List of all lowercased profiles that are mentioned in the StoryItem’s caption, without preceeding @.

New in version 4.10.

property date: datetime¶: Synonym to date_utc

property date_local: datetime¶: Timestamp when the StoryItem was created (local time zone).

Changed in version 4.9: Return timezone aware datetime object.

property date_utc: datetime¶: Timestamp when the StoryItem was created (UTC).

property expiring_local: datetime¶: Timestamp when the StoryItem will get unavailable (local time zone).

property expiring_utc: datetime¶: Timestamp when the StoryItem will get unavailable (UTC).

classmethod from_mediaid(context: InstaloaderContext, mediaid: int)¶: Create a StoryItem object from a given mediaid.

New in version 4.9.

property is_video: bool¶: True if the StoryItem is a video.

property mediaid: int¶: The mediaid is a decimal representation of the media shortcode.

property owner_id: int¶: The ID of the StoryItem owner.

property owner_profile: Profile¶: Profile instance of the story item’s owner.

property owner_username: str¶: The StoryItem owner’s lowercase name.

property pcaption: str¶: Printable caption, useful as a format specifier for –filename-pattern.

New in version 4.10.

property profile: str¶: Synonym to owner_username

property shortcode: str¶: Convert mediaid to a shortcode-like string, allowing {shortcode} to be used with --filename-pattern.

property typename: str¶: Type of post, GraphStoryImage or GraphStoryVideo

property url: str¶: URL of the picture / video thumbnail of the StoryItem

property video_url: str | None¶: URL of the video, or None.

Highlights¶

class instaloader.Highlight(context: InstaloaderContext, node: Dict[str, Any], owner: Profile | None = None)¶

Structure representing a user’s highlight with its associated story items.

Provides methods for accessing highlight properties, as well as Highlight.get_items() to request associated StoryItem nodes. Highlights are returned by Instaloader.get_highlights().

With a logged-in Instaloader instance L, you may download all highlights of a Profile instance USER with:

for highlight in L.get_highlights(USER):
    # highlight is a Highlight object
    for item in highlight.get_items():
        # item is a StoryItem object
        L.download_storyitem(item, '{}/{}'.format(highlight.owner_username, highlight.title))

This class implements == and is hashable.

Parameters:

context – InstaloaderContext instance used for additional queries if necessary.
node – Dictionary containing the available information of the highlight as returned by Instagram.
owner – Profile instance representing the owner profile of the highlight.

Bases: Story

New in version 4.1.

property cover_cropped_url: str¶: URL of the cropped version of the cover.

property cover_url: str¶: URL of the highlights’ cover.

get_items() → Iterator[StoryItem]¶: Retrieve all associated highlight items.

property itemcount: int¶: Count of items associated with the Highlight instance.

property last_seen_local: datetime | None¶: Timestamp of the most recent StoryItem that has been watched or None (local time zone).

property last_seen_utc: datetime | None¶: Timestamp of the most recent StoryItem that has been watched or None (UTC).

property latest_media_local: datetime¶: Timestamp when the last item of the story was created (local time zone).

property latest_media_utc: datetime¶: Timestamp when the last item of the story was created (UTC).

property owner_id: int¶: The story owner’s ID.

property owner_profile: Profile¶: Profile instance of the highlights’ owner.

property owner_username: str¶: The story owner’s lowercase username.

property title: str¶: The title of these highlights.

property unique_id: int¶: A unique ID identifying this set of highlights.

Profiles¶

class instaloader.Profile(context: InstaloaderContext, node: Dict[str, Any])¶

An Instagram Profile.

Provides methods for accessing profile properties, as well as Profile.get_posts() and for own profile Profile.get_saved_posts().

Get instances with Post.owner_profile(), StoryItem.owner_profile(), Profile.get_followees(), Profile.get_followers() or:

L = Instaloader()
profile = Profile.from_username(L.context, USERNAME)

Provides Profile.get_posts() and for own profile Profile.get_saved_posts() to iterate over associated Post objects:

for post in profile.get_posts():
    L.download_post(post, target=profile.username)

Profile.get_followees() and Profile.get_followers():

print("{} follows these profiles:".format(profile.username))
for followee in profile.get_followees():
    print(followee.username)

Also, this class implements == and is hashable.

property biography: str¶

property biography_hashtags: List[str]¶: List of all lowercased hashtags (without preceeding #) that occur in the Profile’s biography.

New in version 4.10.

property biography_mentions: List[str]¶: List of all lowercased profiles that are mentioned in the Profile’s biography, without preceeding @.

New in version 4.10.

property blocked_by_viewer: bool¶

property business_category_name: str¶: New in version 4.4.

property external_url: str | None¶

property followed_by_viewer: bool¶

property followees: int¶

property followers: int¶

property follows_viewer: bool¶

classmethod from_id(context: InstaloaderContext, profile_id: int)¶

Create a Profile instance from a given userid. If possible, use Profile.from_username() or constructor directly rather than this method, since it requires more requests.

Parameters:

context – Instaloader.context
profile_id – userid

Raises:

ProfileNotExistsException

classmethod from_iphone_struct(context: InstaloaderContext, media: Dict[str, Any])¶: Create a profile from a given iphone_struct.

New in version 4.9.

classmethod from_username(context: InstaloaderContext, username: str)¶

Create a Profile instance from a given username, raise exception if it does not exist.

Parameters:

context – Instaloader.context
username – Username

Raises:

ProfileNotExistsException

property full_name: str¶

get_followed_hashtags() → NodeIterator[Hashtag]¶

Retrieve list of hashtags followed by given profile. To use this, one needs to be logged in and private profiles has to be followed.

Return type:: NodeIterator[Hashtag]

New in version 4.10.

get_followees() → NodeIterator[Profile]¶

Retrieve list of followees (followings) of given profile. To use this, one needs to be logged in and private profiles has to be followed.

Return type:: NodeIterator[Profile]

get_followers() → NodeIterator[Profile]¶

Retrieve list of followers of given profile. To use this, one needs to be logged in and private profiles has to be followed.

Return type:: NodeIterator[Profile]

get_igtv_posts() → NodeIterator[Post]¶

Retrieve all IGTV posts.

Return type:: NodeIterator[Post]

New in version 4.3.

get_posts() → NodeIterator[Post]¶

Retrieve all posts from a profile.

Return type:: NodeIterator[Post]

get_profile_pic_url() → str¶: Deprecated since version 4.0.3.

Use profile_pic_url.

get_saved_posts() → NodeIterator[Post]¶

Get Posts that are marked as saved by the user.

Return type:: NodeIterator[Post]

get_similar_accounts() → Iterator[Profile]¶: Retrieve list of suggested / similar accounts for this profile. To use this, one needs to be logged in.

New in version 4.4.

get_tagged_posts() → NodeIterator[Post]¶

Retrieve all posts where a profile is tagged.

Return type:: NodeIterator[Post]

New in version 4.0.7.

property has_blocked_viewer: bool¶

property has_highlight_reels: bool¶: Deprecated since version 4.0.6: Always returns True since Issue #153.

Before broken, this indicated whether the Profile had available stories.

property has_public_story: bool¶

property has_requested_viewer: bool¶

property has_viewable_story: bool¶: Deprecated since version 4.0.6.

Some stories are private. This property determines if the Profile has at least one story which can be viewed using the associated InstaloaderContext, i.e. the viewer has privileges to view it.

property igtvcount: int¶

property is_business_account: bool¶: New in version 4.4.

property is_private: bool¶

property is_verified: bool¶

property mediacount: int¶

classmethod own_profile(context: InstaloaderContext)¶

Return own profile if logged-in.

Parameters:: context – Instaloader.context

New in version 4.5.2.

property profile_pic_url: str¶: Return URL of profile picture. If logged in, the HD version is returned, otherwise a lower-quality version.

New in version 4.0.3.

Changed in version 4.2.1: Require being logged in for HD version (as required by Instagram).

property profile_pic_url_no_iphone: str¶: Return URL of lower-quality profile picture.

New in version 4.9.3.

property requested_by_viewer: bool¶

property userid: int¶: User ID

property username: str¶: Profile Name

Hashtags¶

class instaloader.Hashtag(context: InstaloaderContext, node: Dict[str, Any])¶

An Hashtag.

Analogous to Profile, get an instance with:

L = Instaloader()
hashtag = Hashtag.from_name(L.context, HASHTAG)

To then download the Hashtag’s Posts, do:

for post in hashtag.get_posts():
   L.download_post(post, target="#"+hashtag.name)

Also, this class implements == and is hashable.

Changed in version 4.9: Removed get_related_tags() and is_top_media_only as these features were removed from Instagram.

New in version 4.4.

property allow_following: bool¶

property description: str | None¶

classmethod from_name(context: InstaloaderContext, name: str)¶

Create a Hashtag instance from a given hashtag name, without preceeding ‘#’. Raises an Exception if there is no hashtag with the given name.

Parameters:

context – Instaloader.context
name – Hashtag, without preceeding ‘#’

Raises:

QueryReturnedNotFoundException

get_all_posts() → Iterator[Post]¶: Yields all posts, i.e. all most recent posts and the top posts, in almost-chronological order.

get_posts() → Iterator[Post]¶: Yields the recent posts associated with this hashtag.

Deprecated since version 4.9: Use Hashtag.get_posts_resumable() as this method may return incorrect results (Issue #1457)

get_posts_resumable() → NodeIterator[Post]¶

Get the recent posts of the hashtag in a resumable fashion.

Return type:: NodeIterator[Post]

New in version 4.9.

get_top_posts() → Iterator[Post]¶: Yields the top posts of the hashtag.

property hashtagid: int¶

property is_following: bool¶

property mediacount: int¶

The count of all media associated with this hashtag.

The number of posts with a certain hashtag may differ from the number of posts that can actually be accessed, as the hashtag count might include private posts

property name¶: Hashtag name lowercased, without preceeding ‘#’

property profile_pic_url: str¶

TopSearchResults¶

class instaloader.TopSearchResults(context: InstaloaderContext, searchstring: str)¶

An invocation of this class triggers a search on Instagram for the provided search string.

Provides methods to access the search results as profiles (Profile), locations (PostLocation) and hashtags.

Parameters:

context – Instaloader.context used to send the query for the search.
searchstring – String to search for with Instagram’s “top search”.

New in version 4.3.

get_hashtag_strings() → Iterator[str]¶: Provides the hashtags from the search result as strings.

get_hashtags() → Iterator[Hashtag]¶: Provides the hashtags from the search result.

New in version 4.4.

get_locations() → Iterator[PostLocation]¶: Provides instances of PostLocation from the search result.

get_prefixed_usernames() → Iterator[str]¶: Provides all profile names from the search result that start with the search string.

get_profiles() → Iterator[Profile]¶: Provides the Profile instances from the search result.

property searchstring: str¶: The string that was searched for on Instagram to produce this TopSearchResults instance.

TitlePic¶

class instaloader.TitlePic(profile: Profile | None, target: str | Path, typename: str, filename: str, date_utc: datetime | None)¶

New in version 4.8.

property date: datetime | None¶

property date_local: datetime | None¶

property date_utc: datetime | None¶

property filename: str¶

property owner_id: str | Path¶

property owner_username: str | Path¶

property profile: str | Path¶

property target: str | Path¶

property typename: str¶

Loading and Saving¶

Post, StoryItem, Profile, Hashtag and FrozenNodeIterator can be saved and loaded to/from JSON files.

instaloader.load_structure(context: InstaloaderContext, json_structure: dict) → Post | Profile | StoryItem | Hashtag | FrozenNodeIterator¶

Loads a Post, Profile, StoryItem, Hashtag or FrozenNodeIterator from a json structure.

Parameters:

context – Instaloader.context linked to the new object, used for additional queries if neccessary.
json_structure – Instaloader JSON structure

New in version 4.8.

instaloader.load_structure_from_file(context: InstaloaderContext, filename: str) → Post | Profile | StoryItem | Hashtag | FrozenNodeIterator¶

Loads a Post, Profile, StoryItem, Hashtag or FrozenNodeIterator from a ‘.json’ or ‘.json.xz’ file that has been saved by save_structure_to_file().

Parameters:

context – Instaloader.context linked to the new object, used for additional queries if neccessary.
filename – Filename, ends in ‘.json’ or ‘.json.xz’

instaloader.get_json_structure(structure: Post | Profile | StoryItem | Hashtag | FrozenNodeIterator) → dict¶

Returns Instaloader JSON structure for a Post, Profile, StoryItem, Hashtag: or FrozenNodeIterator so that it can be loaded by load_structure().

Parameters:: structure – Post, Profile, StoryItem or Hashtag

New in version 4.8.

instaloader.save_structure_to_file(structure: Post | Profile | StoryItem | Hashtag | FrozenNodeIterator, filename: str) → None¶

Saves a Post, Profile, StoryItem, Hashtag or FrozenNodeIterator to a ‘.json’ or ‘.json.xz’ file such that it can later be loaded by load_structure_from_file().

If the specified filename ends in ‘.xz’, the file will be LZMA compressed. Otherwise, a pretty-printed JSON file will be created.

Parameters:

structure – Post, Profile, StoryItem or Hashtag
filename – Filename, ends in ‘.json’ or ‘.json.xz’

LatestStamps¶

class instaloader.LatestStamps(latest_stamps_file)¶

LatestStamps class.

Convenience class for retrieving and storing data from the --latest-stamps file.

Parameters:: latest_stamps_file – path to file.

New in version 4.8.

IGTV_TIMESTAMP = 'igtv-timestamp'¶

ISO_FORMAT = '%Y-%m-%dT%H:%M:%S.%f%z'¶

POST_TIMESTAMP = 'post-timestamp'¶

PROFILE_ID = 'profile-id'¶

PROFILE_PIC = 'profile-pic'¶

STORY_TIMESTAMP = 'story-timestamp'¶

TAGGED_TIMESTAMP = 'tagged-timestamp'¶

get_last_igtv_timestamp(profile_name: str) → datetime¶: Returns timestamp of last download of a profile’s igtv posts.

get_last_post_timestamp(profile_name: str) → datetime¶: Returns timestamp of last download of a profile’s posts.

get_last_story_timestamp(profile_name: str) → datetime¶: Returns timestamp of last download of a profile’s stories.

get_last_tagged_timestamp(profile_name: str) → datetime¶: Returns timestamp of last download of a profile’s tagged posts.

get_profile_id(profile_name: str) → int | None¶: Returns stored ID of profile.

get_profile_pic(profile_name: str) → str¶: Returns filename of profile’s last downloaded profile pic.

rename_profile(old_profile: str, new_profile: str)¶: Renames a profile.

save_profile_id(profile_name: str, profile_id: int)¶: Stores ID of profile.

set_last_igtv_timestamp(profile_name: str, timestamp: datetime)¶: Sets timestamp of last download of a profile’s igtv posts.

set_last_post_timestamp(profile_name: str, timestamp: datetime)¶: Sets timestamp of last download of a profile’s posts.

set_last_story_timestamp(profile_name: str, timestamp: datetime)¶: Sets timestamp of last download of a profile’s stories.

set_last_tagged_timestamp(profile_name: str, timestamp: datetime)¶: Sets timestamp of last download of a profile’s tagged posts.

set_profile_pic(profile_name: str, profile_pic: str)¶: Sets filename of profile’s last downloaded profile pic.

Next Section

Resumable Iterations