Instagram Structures

Posts

class Post(context, node, owner_profile=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
classmethod from_shortcode(context, shortcode)

Create a post object from a given shortcode

classmethod from_mediaid(context, mediaid)

Create a post object from a given mediaid

classmethod from_iphone_struct(context, media)

Create a post from a given iphone_struct.

New in version 4.9.

static shortcode_to_mediaid(code)
Return type

int

static mediaid_to_shortcode(mediaid)
Return type

str

static supported_graphql_types()

The values of __typename fields that the Post class can handle.

Return type

List[str]

property shortcode

Media shortcode. URL of the post is instagram.com/p/<shortcode>/.

Return type

str

property mediaid

The mediaid is a decimal representation of the media shortcode.

Return type

int

property title

Title of post

Return type

Optional[str]

property owner_profile

Profile instance of the Post’s owner.

Return type

Profile

property owner_username

The Post’s lowercase owner name.

Return type

str

property owner_id

The ID of the Post’s owner.

Return type

int

property date_local

Timestamp when the post was created (local time zone).

Changed in version 4.9: Return timezone aware datetime object.

Return type

datetime

property date_utc

Timestamp when the post was created (UTC).

Return type

datetime

property date

Synonym to date_utc

Return type

datetime

property profile

Synonym to owner_username

Return type

str

property url

URL of the picture / video thumbnail of the post

Return type

str

property typename

Type of post, GraphImage, GraphVideo or GraphSidecar

Return type

str

property mediacount

The number of media in a sidecar Post, or 1 if the Post it not a sidecar.

New in version 4.6.

Return type

int

get_is_videos()

Return a list containing the is_video property for each media in the post.

New in version 4.7.

Return type

List[bool]

get_sidecar_nodes(start=0, end=-1)

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.

Return type

Iterator[PostSidecarNode]

property caption

Caption.

Return type

Optional[str]

property caption_hashtags

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

Return type

List[str]

property caption_mentions

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

Return type

List[str]

property pcaption

Printable caption, useful as a format specifier for –filename-pattern.

New in version 4.2.6.

Return type

str

property accessibility_caption

Accessibility caption of the post, if available.

New in version 4.9.

Return type

Optional[str]

property tagged_users

List of all lowercased users that are tagged in the Post.

Return type

List[str]

property is_video

True if the Post is a video.

Return type

bool

property video_url

URL of the video, or None.

Return type

Optional[str]

property video_view_count

View count of the video, or None.

New in version 4.2.6.

Return type

Optional[int]

property video_duration

Duration of the video in seconds, or None.

New in version 4.2.6.

Return type

Optional[float]

property viewer_has_liked

Whether the viewer has liked the post, or None if not logged in.

Return type

Optional[bool]

property likes

Likes count

Return type

int

property comments

Comment count including answers

Return type

int

get_comments()

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.

Return type

Iterable[PostComment]

get_likes()

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

Return type

Iterator[Profile]

property is_sponsored

Whether Post is a sponsored post, equivalent to non-empty Post.sponsor_users().

New in version 4.4.

Return type

bool

property sponsor_users

The Post’s sponsors.

New in version 4.4.

Return type

List[Profile]

property location

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.

Return type

Optional[PostLocation]

property is_pinned

True if this Post has been pinned by at least one user.

Return type

bool

Additionally, the following trivial structures are defined:

class PostSidecarNode

Item of a Sidecar Post.

is_video

Whether this node is a video.

display_url

URL of image or video thumbnail.

video_url

URL of video or None.

class PostComment(id, created_at_utc, text, owner, likes_count, answers)
id

ID number of comment.

created_at_utc

datetime when comment was created (UTC).

text

Comment text.

owner

Owner Profile of the comment.

likes_count

Number of likes on comment.

answers

Iterator which yields all PostCommentAnswers for the comment.

class PostCommentAnswer(id, created_at_utc, text, owner, likes_count)
id

ID number of comment.

created_at_utc

datetime when comment was created (UTC).

text

Comment text.

owner

Owner Profile of the comment.

likes_count

Number of likes on comment.

class PostLocation(id, name, slug, has_public_page, lat, lng)
id

ID number of location.

name

Location name.

slug

URL friendly variant of location name.

has_public_page

Whether location has a public page.

lat

Latitude (float or None).

lng

Longitude (float or None).

User Stories

class Story(context, node)

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
property unique_id

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.

Return type

Union[str, int]

property last_seen_local

Timestamp of the most recent StoryItem that has been watched or None (local time zone).

Return type

Optional[datetime]

property last_seen_utc

Timestamp of the most recent StoryItem that has been watched or None (UTC).

Return type

Optional[datetime]

property latest_media_local

Timestamp when the last item of the story was created (local time zone).

Return type

datetime

property latest_media_utc

Timestamp when the last item of the story was created (UTC).

Return type

datetime

property itemcount

Count of items associated with the Story instance.

Return type

int

property owner_profile

Profile instance of the story owner.

Return type

Profile

property owner_username

The story owner’s lowercase username.

Return type

str

property owner_id

The story owner’s ID.

Return type

int

get_items()

Retrieve all items from a story.

Return type

Iterator[StoryItem]

class StoryItem(context, node, owner_profile=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
property mediaid

The mediaid is a decimal representation of the media shortcode.

Return type

int

property shortcode

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

Return type

str

classmethod from_mediaid(context, mediaid)

Create a StoryItem object from a given mediaid.

New in version 4.9.

property owner_profile

Profile instance of the story item’s owner.

Return type

Profile

property owner_username

The StoryItem owner’s lowercase name.

Return type

str

property owner_id

The ID of the StoryItem owner.

Return type

int

property date_local

Timestamp when the StoryItem was created (local time zone).

Changed in version 4.9: Return timezone aware datetime object.

Return type

datetime

property date_utc

Timestamp when the StoryItem was created (UTC).

Return type

datetime

property date

Synonym to date_utc

Return type

datetime

property profile

Synonym to owner_username

Return type

str

property expiring_local

Timestamp when the StoryItem will get unavailable (local time zone).

Return type

datetime

property expiring_utc

Timestamp when the StoryItem will get unavailable (UTC).

Return type

datetime

property url

URL of the picture / video thumbnail of the StoryItem

Return type

str

property typename

Type of post, GraphStoryImage or GraphStoryVideo

Return type

str

property caption

Caption.

New in version 4.10.

Return type

Optional[str]

property caption_hashtags

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

New in version 4.10.

Return type

List[str]

property caption_mentions

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

New in version 4.10.

Return type

List[str]

property pcaption

Printable caption, useful as a format specifier for –filename-pattern.

New in version 4.10.

Return type

str

property is_video

True if the StoryItem is a video.

Return type

bool

property video_url

URL of the video, or None.

Return type

Optional[str]

Highlights

class Highlight(context, node, owner=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

Bases: Story

New in version 4.1.

property unique_id

A unique ID identifying this set of highlights.

Return type

int

property owner_profile

Profile instance of the highlights’ owner.

Return type

Profile

property title

The title of these highlights.

Return type

str

property cover_url

URL of the highlights’ cover.

Return type

str

property cover_cropped_url

URL of the cropped version of the cover.

Return type

str

property itemcount

Count of items associated with the Highlight instance.

Return type

int

get_items()

Retrieve all associated highlight items.

Return type

Iterator[StoryItem]

property last_seen_local

Timestamp of the most recent StoryItem that has been watched or None (local time zone).

Return type

Optional[datetime]

property last_seen_utc

Timestamp of the most recent StoryItem that has been watched or None (UTC).

Return type

Optional[datetime]

property latest_media_local

Timestamp when the last item of the story was created (local time zone).

Return type

datetime

property latest_media_utc

Timestamp when the last item of the story was created (UTC).

Return type

datetime

property owner_id

The story owner’s ID.

Return type

int

property owner_username

The story owner’s lowercase username.

Return type

str

Profiles

class Profile(context, node)

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.

classmethod from_username(context, username)

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

See also Instaloader.check_profile_id().

Parameters
Raises

ProfileNotExistsException

classmethod from_id(context, profile_id)

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, media)

Create a profile from a given iphone_struct.

New in version 4.9.

classmethod own_profile(context)

Return own profile if logged-in.

Parameters

context (InstaloaderContext) – Instaloader.context

New in version 4.5.2.

property userid

User ID

Return type

int

property username

Profile Name

Return type

str

property is_private
Return type

bool

property followed_by_viewer
Return type

bool

property mediacount
Return type

int

property igtvcount
Return type

int

property followers
Return type

int

property followees
Return type

int

property external_url
Return type

Optional[str]

property is_business_account

New in version 4.4.

Return type

bool

property business_category_name

New in version 4.4.

Return type

str

property biography
Return type

str

property biography_hashtags

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

New in version 4.10.

Return type

List[str]

property biography_mentions

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

New in version 4.10.

Return type

List[str]

property blocked_by_viewer
Return type

bool

property follows_viewer
Return type

bool

property full_name
Return type

str

property has_blocked_viewer
Return type

bool

property has_highlight_reels

Deprecated since version 4.0.6: Always returns True since Issue #153.

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

Return type

bool

property has_public_story
Return type

bool

property has_viewable_story

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.

Return type

bool

property has_requested_viewer
Return type

bool

property is_verified
Return type

bool

property requested_by_viewer
Return type

bool

property profile_pic_url

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

Return type

str

property profile_pic_url_no_iphone

Return URL of lower-quality profile picture.

New in version 4.9.3.

Return type

str

get_profile_pic_url()

Deprecated since version 4.0.3.

Use profile_pic_url.

Return type

str

get_posts()

Retrieve all posts from a profile.

Return type

NodeIterator[Post]

get_saved_posts()

Get Posts that are marked as saved by the user.

Return type

NodeIterator[Post]

get_tagged_posts()

Retrieve all posts where a profile is tagged.

Return type

NodeIterator[Post]

New in version 4.0.7.

get_igtv_posts()

Retrieve all IGTV posts.

Return type

NodeIterator[Post]

New in version 4.3.

get_followed_hashtags()

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_followers()

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_followees()

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_similar_accounts()

Retrieve list of suggested / similar accounts for this profile. To use this, one needs to be logged in.

New in version 4.4.

Return type

Iterator[Profile]

Hashtags

class Hashtag(context, node)

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.

classmethod from_name(context, name)

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

property name

Hashtag name lowercased, without preceeding ‘#’

property hashtagid
Return type

int

property profile_pic_url
Return type

str

property description
Return type

Optional[str]

property allow_following
Return type

bool

property is_following
Return type

bool

get_top_posts()

Yields the top posts of the hashtag.

Return type

Iterator[Post]

property mediacount

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

Return type

int

get_posts()

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)

Return type

Iterator[Post]

get_all_posts()

Yields all posts, i.e. all most recent posts and the top posts, in almost-chronological order.

Return type

Iterator[Post]

get_posts_resumable()

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

Return type

NodeIterator[Post]

New in version 4.9.

TopSearchResults

class TopSearchResults(context, searchstring)

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

New in version 4.3.

get_profiles()

Provides the Profile instances from the search result.

Return type

Iterator[Profile]

get_prefixed_usernames()

Provides all profile names from the search result that start with the search string.

Return type

Iterator[str]

get_locations()

Provides instances of PostLocation from the search result.

Return type

Iterator[PostLocation]

get_hashtag_strings()

Provides the hashtags from the search result as strings.

Return type

Iterator[str]

get_hashtags()

Provides the hashtags from the search result.

New in version 4.4.

Return type

Iterator[Hashtag]

property searchstring

The string that was searched for on Instagram to produce this TopSearchResults instance.

Return type

str

Loading and Saving

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

load_structure(context, json_structure)

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

Parameters

New in version 4.8.

Return type

Union[Post, Profile, StoryItem, Hashtag, FrozenNodeIterator]

load_structure_from_file(context, filename)

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
Return type

Union[Post, Profile, StoryItem, Hashtag, FrozenNodeIterator]

get_json_structure(structure)
Returns Instaloader JSON structure for a Post, Profile, StoryItem, Hashtag

or FrozenNodeIterator so that it can be loaded by load_structure().

Parameters

structure (Union[Post, Profile, StoryItem, Hashtag, FrozenNodeIterator]) – Post, Profile, StoryItem or Hashtag

New in version 4.8.

Return type

dict

save_structure_to_file(structure, filename)

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
Return type

None

LatestStamps

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

PROFILE_ID = 'profile-id'
PROFILE_PIC = 'profile-pic'
POST_TIMESTAMP = 'post-timestamp'
TAGGED_TIMESTAMP = 'tagged-timestamp'
IGTV_TIMESTAMP = 'igtv-timestamp'
STORY_TIMESTAMP = 'story-timestamp'
ISO_FORMAT = '%Y-%m-%dT%H:%M:%S.%f%z'
get_profile_id(profile_name)

Returns stored ID of profile.

Return type

Optional[int]

save_profile_id(profile_name, profile_id)

Stores ID of profile.

rename_profile(old_profile, new_profile)

Renames a profile.

get_last_post_timestamp(profile_name)

Returns timestamp of last download of a profile’s posts.

Return type

datetime

set_last_post_timestamp(profile_name, timestamp)

Sets timestamp of last download of a profile’s posts.

get_last_tagged_timestamp(profile_name)

Returns timestamp of last download of a profile’s tagged posts.

Return type

datetime

set_last_tagged_timestamp(profile_name, timestamp)

Sets timestamp of last download of a profile’s tagged posts.

get_last_igtv_timestamp(profile_name)

Returns timestamp of last download of a profile’s igtv posts.

Return type

datetime

set_last_igtv_timestamp(profile_name, timestamp)

Sets timestamp of last download of a profile’s igtv posts.

get_last_story_timestamp(profile_name)

Returns timestamp of last download of a profile’s stories.

Return type

datetime

set_last_story_timestamp(profile_name, timestamp)

Sets timestamp of last download of a profile’s stories.

get_profile_pic(profile_name)

Returns filename of profile’s last downloaded profile pic.

Return type

str

set_profile_pic(profile_name, profile_pic)

Sets filename of profile’s last downloaded profile pic.

Next Section

Resumable Iterations