instagrapi
Fast and effective Instagram Private API wrapper (public+private requests and challenge resolver). Use the most recent version of the API from Instagram, which was obtained using reverse-engineering with Charles Proxy.
Instagram API valid for 27 September 2020 (last reverse-engineering check) Support Python>=3.6
Features
- Performs public (
_gqlor_a1suffix methods) or private/auth (_v1suffix methods) requests depending on the situation (to avoid Instagram limits) - Challenge Resolver have Email (as well as recipes for automating receive a code from email) and SMS handlers
- Support upload a Photo, Video, IGTV, Albums and Stories
- Support work with User, Media, Insights, Collections and Direct objects
- Insights by posts and stories
- Build stories with custom background and font animation
Install
pip install instagrapi
Tests
python -m unittest tests
python -m unittest tests.ClientPublicTestCase
Requests
Public(anonymous) methods had suffix_gql(InstagramGraphQL) or_a1(examplehttps://www.instagram.com/adw0rd/?__a=1)Private(authorized request) methods have_v1suffix
The first request to fetch media/user is public (anonymous), if instagram raise exception, then use private (authorized).
Example (pseudo-code):
def media_info(media_pk):
try:
return self.media_info_gql(media_pk)
except ClientError as e:
# Restricted Video: This video is not available in your country.
# Or media from private account
return self.media_info_v1(media_pk)
Usage
from instagrapi import Client
cl = Client()
cl.login(ACCOUNT_USERNAME, ACCOUNT_PASSWORD)
user_id = cl.user_id_from_username("adw0rd")
medias = cl.user_medias(user_id, 20)
Account
This is your authorized account
| Method | Return | Description |
|---|---|---|
| login(username: str, password: str, settings: dict = {}) | Bool | Login by username and password |
| relogin() | Bool | Relogin with clean cookies (required cl.username/cl.password) |
| login_by_sessionid(sessionid: str) | Bool | Login by sessionid from Instagram site |
| get_settings() | Dict | Return settings dict (more details below) |
| set_proxy(dsn: str) | Dict | Support socks and http/https proxy |
| cookie_dict | Dict | Return cookies |
| user_id | Int | Return you user_id (after login) |
| device | Dict | Return device dict which we pass to Instagram |
| set_device(device: dict) | None | Change device settings |
| set_user_agent(user_agent: str) | None | Change User-Agent header |
| base_headers | Dict | Base headers for Instagram |
Example:
cl.login("instagrapi", "42")
# cl.login_by_sessionid("peiWooShooghahdi2Eip7phohph0eeng")
cl.set_proxy("socks5://127.0.0.1:30235")
# cl.set_proxy("http://127.0.0.1:8080")
print(cl.get_settings())
print(cl.user_info(cl.user_id))
You can pass settings to the Client (and save cookies), it has the following format:
settings = {
"uuids": {
"phone_id": "57d64c41-a916-3fa5-bd7a-3796c1dab122",
"uuid": "8aa373c6-f316-44d7-b49e-d74563f4a8f3",
"client_session_id": "6c296d0a-3534-4dce-b5aa-a6a6ab017443",
"advertising_id": "8dc88b76-dfbc-44dc-abbc-31a6f1d54b04",
"device_id": "android-e021b636049dc0e9"
},
"cookies": {}, # set here you saved cookies
"last_login": 1596069420.0000145,
"device_settings": {
"cpu": "h1",
"dpi": "640dpi",
"model": "h1",
"device": "RS988",
"resolution": "1440x2392",
"app_version": "117.0.0.28.123",
"manufacturer": "LGE/lge",
"version_code": "168361634",
"android_release": "6.0.1",
"android_version": 23
},
"user_agent": "Instagram 117.0.0.28.123 Android (23/6.0.1; ...US; 168361634)"
}
cl = Client(username, password, settings=settings)
This values send to Instagram API.
Media
Viewing and editing publications (medias)
media_id- String ID"{media_id}_{user_id}", example"2277033926878261772_1903424587"(Instagram terminology)media_pk- Integer ID (real media id), example2277033926878261772(Instagram terminology)code- Short code (slug for media), exampleBjNLpA1AhXMfrom"https://www.instagram.com/p/BjNLpA1AhXM/"url- URL to media publication
| Method | Return | Description |
|---|---|---|
| media_id(media_pk: int) | Str | Return media_id by media_pk |
| media_pk(media_id: str) | Int | Return media_pk by media_id |
| media_pk_from_code(code: str) | Int | Return media_pk |
| media_pk_from_url(url: str) | Int | Return media_pk |
| media_info(media_pk: int) | Dict[full media] | Return media info |
| media_delete(media_pk: int) | Bool | Delete media |
| media_edit(media_pk: int, caption: str) | Bool | Change caption for media |
| media_user(media_pk: int) | Dict[user] | Get user info for media |
| media_oembed(url: str) | Dict[short media] | Return short media info by media URL |
| media_comment(media_id: str, message: str) | Bool | Write message to media |
| media_comments(media_id: str) | List[comment] | Get all comments |
Example:
>>> cl.media_pk_from_code("B-fKL9qpeab")
2278584739065882267
>>> cl.media_pk_from_code("B8jnuB2HAbyc0q001y3F9CHRSoqEljK_dgkJjo0")
2243811726252050162
>>> cl.media_pk_from_url("https://www.instagram.com/p/BjNLpA1AhXM/")
1787135824035452364
>>> cl.media_oembed("https://www.instagram.com/p/B3mr1-OlWMG/")
{'version': '1.0',
'title': 'В гостях у ДК @delai_krasivo_kaifui',
'author_name': 'adw0rd',
'author_url': 'https://www.instagram.com/adw0rd',
'author_id': 1903424587,
'media_id': '2154602296692269830_1903424587',
'provider_name': 'Instagram',
'provider_url': 'https://www.instagram.com',
'type': 'rich',
'width': 658,
'height': None,
'html': '<blockquote>...',
'thumbnail_url': 'https://instagram.frix7-1.fna.fbcdn.net/v....135355164531920_1445273950655800983_n.jpg',
'thumbnail_width': 640,
'thumbnail_height': 480,
'can_view': True}
User
View a list of a user's medias, following and followers
user_id- Integer ID of user, example1903424587
| Method | Return | Description |
|---|---|---|
| user_medias(user_id: int, amount: int = 20) | List[media] | Get list of medias by user_id |
| user_followers(user_id: int) | Dict | Get dict {user_id: user, ...} of followers users |
| user_following(user_id: int) | Dict | Get dict {user_id: user, ...} of following users |
| user_info(user_id: int) | Dict[user] | Get user info |
| user_info_by_username(username: str) | Dict[user] | Get user info by username |
| user_follow(user_id: int) | Bool | Follow user |
| user_unfollow(user_id: int) | Bool | Unfollow user |
| user_id_from_username(username: str) | Int | Get user_id by username |
| username_from_user_id(user_id: int) | Str | Get username by user_id |
Example:
>>> cl.user_followers(cl.user_id).keys()
dict_keys([5563084402, 43848984510, 1498977320, ...])
>>> cl.user_following(cl.user_id)
{
8530598273: {
"pk": 8530598273,
"username": "dhbastards",
"full_name": "The Best DH Skaters Ever",
"is_private": False,
"profile_pic_url": "https://instagram.frix7-1.fna.fbcdn.net/v/t5...9318717440_n.jpg",
"is_verified": False
},
...
}
>>> cl.user_info_by_username('adw0rd')
{'pk': 1903424587,
'username': 'adw0rd',
'full_name': 'Mikhail Andreev',
'is_private': False,
'profile_pic_url': 'https://scontent-arn2-1.cdninstagram.com/v/t51...FB463C5',
'is_verified': False,
'media_count': 102,
'follower_count': 578,
'following_count': 529,
'biography': 'Engineer: Python, JavaScript, Erlang\n@dhbastards ...',
'external_url': 'https://adw0rd.com/',
'is_business': False}
Upload Media as Post (to Feed)
| Method | Return | Description |
|---|---|---|
| photo_upload(path, caption) | Dict[media] | Upload photo (Support JPG files) |
| photo_download(media_pk) | Str[path] | Download photo (Return path to photo with best resoluton) |
| video_upload(path, caption) | Dict[media] | Upload video (Support mp4 files) |
| video_download(media_pk) | Str[path] | Download video (Return path to video with best resoluton) |
| igtv_upload(path, title, caption) | Dict[media] | Upload IGTV (Support mp4 files) |
| igtv_download(media_pk) | Str[path] | Download IGTV (Return path to video with best resoluton) |
| album_upload(paths, caption) | Dict[media] | Upload Album (Support JPG and mp4) |
| album_download(media_pk) | List[path] | Download Album (Return multiple paths to photo and video with best resolutons) |
Stories
Upload medias to you stories. Common arguments:
filepath- Path to media filecaption- Caption for story (now use to fetch mentions)thumbnail- Thumbnail instead capture from source fileusertags- Specify usertags for mention users in storyconfigure_timeout- How long to wait in seconds for a response from Instagram when publishing a storylinks- "Swipe Up" links (now use first)
| Method | Return | Description |
|---|---|---|
| photo_upload_to_story(filepath: str, caption: str, thumbnail: str = None, usertags: list = [], configure_timeout: int = 3, links: list = []) | Dict[media] | Upload photo (Support JPG files) |
| video_upload_to_story(filepath: str, caption: str, thumbnail: str = None, usertags: list = [], configure_timeout: int = 3, links: list = []) | Dict[media] | Upload video (Support mp4 files). |
Examples:
path = cl.video_download(
cl.media_pk_from_url('https://www.instagram.com/p/CGgDsi7JQdS/')
)
cl.video_upload_to_story(
path,
"Credits @adw0rd",
usertags=[
{'user': {'pk': 1903424587, 'name': 'adw0rd'}, 'x': 0.49892962, 'y': 0.703125, 'width': 0.8333333333333334, 'height': 0.125}
],
links=[{'webUri': 'https://adw0rd.com/'}]
)
Collections
| Method | Return | Description |
|---|---|---|
| collections() | List[collection] | Get all account collections |
| collection_medias_by_name(name) | List[media] | Get medias in collection by name |
| collection_medias(collection_id, amount=21, last_media_pk=0) | List[media] | Get medias in collection by collection_id; Use amount=0 to return all medias in collection; Use last_media_pk to return medias by delta |
Insights
In the process of describing
Direct
In the process of describing
Challenge
In the process of describing
Common Exceptions
| Exception | Base | Description |
|---|---|---|
| ClientError | Exception | Base Exception for Instagram calls |
| GenericRequestError | ClientError | Base Exception for Request |
| ClientGraphqlError | ClientError | Exception for GraphQL calls |
| ClientJSONDecodeError | ClientError | JSON Exception |
| ClientConnectionError | ClientError | Connection error |
| ClientBadRequestError | ClientError | HTTP 400 Exception |
| ClientForbiddenError | ClientError | HTTP 403 Exception |
| ClientNotFoundError | ClientError | HTTP 404 Exception |
| ClientThrottledError | ClientError | HTTP 429 Exception |
| ClientRequestTimeout | ClientError | Request Timeout Exception |
| ClientIncompleteReadError | ClientError | Raised when response interrupted |
| ClientLoginRequired | ClientError | Raised when Instagram required Login |
| ReloginAttemptExceeded | ClientError | Raised when all attempts exceeded |
Private Exceptions
| Exception | Base | Description |
|---|---|---|
| PrivateError | ClientError | Base Exception for Private calls (received from Instagram) |
| FeedbackRequired | PrivateError | Raise when get message=feedback_required |
| LoginRequired | PrivateError | Raise when get message=login_required |
| SentryBlock | PrivateError | Raise when get message=sentry_block |
| RateLimitError | PrivateError | Raise when get message=rate_limit_error |
| BadPassword | PrivateError | Raise when get message=bad_password |
| UnknownError | PrivateError | Raise when get unknown message (new message from instagram) |
Challenge Exceptions
| Exception | Base | Description |
|---|---|---|
| ChallengeError | PrivateError | Base Challenge Exception (received from Instagram) |
| ChallengeRedirection | ChallengeError | Raise when get type=CHALLENGE_REDIRECTION |
| ChallengeRequired | ChallengeError | Raise when get message=challenge_required |
| SelectContactPointRecoveryForm | ChallengeError | Raise when get challengeType=SelectContactPointRecoveryForm |
| RecaptchaChallengeForm | ChallengeError | Raise when get challengeType=RecaptchaChallengeForm |
| SubmitPhoneNumberForm | ChallengeError | Raise when get challengeType=SubmitPhoneNumberForm |
Media Exceptions
| Exception | Base | Description |
|---|---|---|
| MediaError | PrivateError | Base Media Exception (received from Instagram) |
| MediaNotFound | MediaError | Raise when user unavailable |
User Exceptions
| Exception | Base | Description |
|---|---|---|
| UserError | PrivateError | Base User Exception (received from Instagram) |
| UserNotFound | UserError | Raise when user unavailable |
Collection Exceptions
| Exception | Base | Description |
|---|---|---|
| CollectionError | PrivateError | Base Collection Exception (received from Instagram) |
| CollectionNotFound | CollectionError | Raise when collection unavailable |
Metadata
Release files for instagrapi 1.1.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| instagrapi-1.1.5.tar.gz | 43.5 kB | Without provenance | Details for instagrapi-1.1.5.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| instagrapi-1.1.5-py3-none-any.whl | Python 3 | none | any | Details for instagrapi-1.1.5-py3-none-any.whl |
Total release size: 138.0 kB
Release files / instagrapi-1.1.5.tar.gz
| Download URL | instagrapi-1.1.5.tar.gz |
|---|---|
| Size | 43.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b24f056eb080001f0b47d4dff34bd5b8605396bcf7ab51a21bd8d936d9209fcb
|
|
BLAKE2b-256 checksum How to use checksums |
3419bb855a7fced47e58b6643b54e351148a641ce20f78dfb475ad3dbf3eaf6c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
Python-urllib/3.8
|
Release files / instagrapi-1.1.5-py3-none-any.whl
| Download URL | instagrapi-1.1.5-py3-none-any.whl |
|---|---|
| Size | 94.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7b5ad407054497d2dca6a3400e66fb60fdcc3469f9cb73e7bfb414a82abd6cb3
|
|
BLAKE2b-256 checksum How to use checksums |
2451609e04c96c4fdc08895e2c6949c7101ea0b04f0e898c30c32372b65afa8e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.2.0 pkginfo/1.6.0 requests/2.24.0 setuptools/50.3.2 requests-toolbelt/0.9.1 tqdm/4.50.2 CPython/3.8.5
|
Security for instagrapi 1.1.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.