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.

Added 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.

Added 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.

Added 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().

Added 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.

Added 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.

Added 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.

Added 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.

Added 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.

Added 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.

Added 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.

Added in version 4.10.

property caption_hashtags: List[str]

List of all lowercased hashtags (without preceeding #) that occur in the StoryItem’s caption.

Added in version 4.10.

property caption_mentions: List[str]

List of all lowercased profiles that are mentioned in the StoryItem’s caption, without preceeding @.

Added 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.

Added 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.

Added 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

Added 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.

Added in version 4.10.

property biography_mentions: List[str]

List of all lowercased profiles that are mentioned in the Profile’s biography, without preceeding @.

Added in version 4.10.

property blocked_by_viewer: bool
property business_category_name: str

Added 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:
Raises:

ProfileNotExistsException

classmethod from_iphone_struct(context: InstaloaderContext, media: Dict[str, Any])

Create a profile from a given iphone_struct.

Added 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.

See also Instaloader.check_profile_id().

Parameters:
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]

Added 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]

Added 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_reels() → NodeIterator[Post]

Retrieve all reels from a profile.

Return type:

NodeIterator[Post]

Added in version 4.14.0.

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.

Added in version 4.4.

get_tagged_posts() → NodeIterator[Post]

Retrieve all posts where a profile is tagged.

Return type:

NodeIterator[Post]

Added 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

Added 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

Added 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.

Added 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.

Added 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.

Added 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:
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]

Added 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”.

Added 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.

Added 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)

Added 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

Added 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

Added 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:

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.

Added 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'
REELS_TIMESTAMP = 'reels-timestamp'
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_reels_timestamp(profile_name: str) → datetime

Returns timestamp of last download of a profile’s reels 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_reels_timestamp(profile_name: str, timestamp: datetime)

Sets timestamp of last download of a profile’s reels 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