Instagrapi

https://github.com/subzeroid/instagrapi
Admin
Instagrapi is a fast and effective unofficial Instagram Private API wrapper for Python, enabling...
Tokens:342,248
Snippets:2,048
Trust Score:8.7
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Setup development environment with uv

Source: https://github.com/subzeroid/instagrapi/blob/master/CONTRIBUTING.md

Commands to create a virtual environment and install dependencies using the uv package manager.

```bash
uv venv
source .venv/bin/activate
uv pip install -e ".[test]"
uv pip install --no-deps "moviepy==2.2.1"
pre-commit install
```

--------------------------------

### Setup development environment with pip

Source: https://github.com/subzeroid/instagrapi/blob/master/CONTRIBUTING.md

Commands to create a virtual environment and install the package with test dependencies using pip.

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[test]"
python -m pip install --no-deps "moviepy==2.2.1"
pre-commit install
```

--------------------------------

### Configure Notification Settings Example

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/notification.md

Example demonstrating how to log in and update specific notification settings.

```python
from instagrapi import Client

cl = Client()
cl.login(USERNAME, PASSWORD)

cl.notification_comments("following_only")
cl.notification_settings("likes", "off")
cl.notification_mute_all("1_hour")
```

--------------------------------

### Execute Example Scripts

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/examples.md

Run the provided example scripts from the command line with various arguments for tasks like profile lookup, media management, and messaging.

```bash
python examples/public_lookup.py instagram
IG_PUBLIC_TRANSPORT=curl python examples/public_lookup.py instagram
python examples/download_user_media.py instagram --amount 5 --folder ./downloads
python examples/monitor_user_content.py instagram --stories --interval 900
python examples/upload_media.py reel ./reel.mp4 --thumbnail ./thumb.jpg --caption "Reel"
python examples/upload_story.py photo ./story.jpg --caption "Story"
python examples/direct_message.py --user-ids 123456789 --text "Hello"
```

--------------------------------

### Example: Using instagrapi Account Methods

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/account.md

This example demonstrates how to use various account management methods from the instagrapi library. It starts by logging in, then retrieves account info, edits the external URL, sets a biography, converts the account to a creator account, downloads a profile picture, changes the profile picture, and confirms a new email and phone number. The output for each method call is shown in the comments.

```python
>>> from instagrapi import Client
>>> cl = Client()
>>> cl.login(USERNAME, PASSWORD)
>>> cl.account_info().dict()
{'pk': 1903424587,
 'username': 'example',
 'full_name': 'Example Example',
 'is_private': False,
 'profile_pic_url': HttpUrl('https://instagram.frix7-1.fna.fbcdn.net/v/t51.2885-19/s150x150/200092102_504535360754500_904902738723095864_n.jpg?tp=1&_nc_ht=instagram.frix7-1.fna.fbcdn.net&_nc_ohc=T2ZT6yA6XzoAX9MvAQA&edm=AJlpnE4BAAAA&ccb=7-4&oh=3865b51bb33b365c9de8bcf9775e519c&oe=60E982F2&_nc_sid=312772'),
 'is_verified': False,
 'biography': 'Engineer: Python, JavaScript, Erlang, Go, Swift\n@dhbastards \n@bestskatetrick \n@asphalt_kings_lb \n@best_drift_daily \n@wrclive \n@surferyone \n@bmxtravel',
 'external_url': 'https://example.org/',
 'is_business': False,
 'birthday': '1984-01-01',
 'phone_number': '+79991234567',
 'gender': 1,
 'email': '...@gmail.com'}

>>> cl.account_edit(external_url='https://github.com/subzeroid/instagrapi')
Account(pk=1903424587, username='example', ..., external_url='https://github.com/subzeroid/instagrapi')

>>> cl.account_set_biography("Python, APIs, and automation")
True

>>> cl.account_convert_to_creator(category_id="2347428775505624")
Account(pk=1903424587, username='example', ..., account_type=3)

>>> media_pk = cl.media_pk_from_url('https://www.instagram.com/p/BWnh360Fitr/')
1560364774164147051

>>> profile_pic_path = cl.photo_download(media_pk, folder='/tmp')
PosixPath('/tmp/example_1560364774164147051.jpg')

>>> cl.account_change_picture(profile_pic_path)
UserShort(pk=1903424587, username='example', ...)

>>> cl.send_confirm_email("addr@example.com")
{
    'is_email_legit': False,
    'title': 'Email Already in Use',
    'body': 'The email address you entered is already used on your account. Enter a different one to update your contact info.',
    'error_type': 'email_unchanged',
    'status': 'ok'
}

>>> cl.confirm_email("addr@example.com", "123456")
{'status': 'ok'}

>>> cl.send_confirm_phone_number("+5599999999")
{
    'action': 'sms_sent',
    'phone_verification_settings': {'max_sms_count': 2,
    'resend_sms_delay_sec': 60,
    'robocall_count_down_time_sec': 30,
    'robocall_after_max_sms': True},
    'status': 'ok'
}

>>> cl.confirm_phone_number("+5599999999", "123456")
{'status': 'ok'}
```

--------------------------------

### Download and interact with Instagram stories using instagrapi

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/story.md

Python example demonstrating story download, info retrieval, archive access, and poll voting. Uses cl.story_pk_from_url to get a story PK from a URL, cl.story_download to download the story, cl.story_info to fetch story details, cl.story_download_by_url for direct media URLs, cl.archive_story_days and cl.archive_stories for archive access, and cl.story_poll_vote to vote in a poll. The example shows the returned paths and values.

```python
>>> cl.story_download(cl.story_pk_from_url('https://www.instagram.com/stories/example/2581281926631793076/'))
PosixPath('/app/189361307_229642088942817_9180243596650100310_n.mp4')

>>> s = cl.story_info(2581281926631793076)

>>> cl.story_download_by_url(s.video_url)  # url to mp4 file
PosixPath('/app/189361307_229642088942817_9180243596650100310_n.mp4')

>>> cl.story_download_by_url(s.thumbnail_url)  # URL to jpg file
PosixPath('/app/191260083_2908005872746895_8988438451809588865_n.jpg')

>>> days = cl.archive_story_days(amount=1)
>>> days[0].id
'archiveDay:1710000000000'

>>> archived = cl.archive_stories(amount=5)
>>> [story.pk for story in archived]
['3155832952940083788']

>>> story = cl.user_stories(USER_ID, amount=1)[0]
>>> cl.story_poll_vote(story.id, story.polls[0].id, 0)  # vote for the first option
True
```

--------------------------------

### Install pre-commit globally with pipx

Source: https://github.com/subzeroid/instagrapi/blob/master/CONTRIBUTING.md

Use pipx to install the pre-commit tool globally.

```bash
pipx install pre-commit
```

--------------------------------

### user_guides_v1(user_id: int) -> List[Guide]

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/user.md

Retrieves a list of guides created by the user.

```APIDOC
## user_guides_v1(user_id: int)

### Description
Get user's guides.

### Method
SDK Method

### Parameters
- **user_id** (int) - Required - Integer ID of user, example `1903424587`

### Return
List[Guide]
```

--------------------------------

### Install instagrapi and configure environment variables

Source: https://github.com/subzeroid/instagrapi/blob/master/examples/README.md

Install the package and set required environment variables for authentication and session persistence.

```bash
python -m pip install -U instagrapi

export IG_USERNAME="your_username"
export IG_PASSWORD="your_password"
export IG_SESSION_FILE="./ig_settings.json"
```

--------------------------------

### Minimal upload example

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/pydroid.md

A basic example of uploading a clip with a thumbnail in Pydroid.

```python
from pathlib import Path

from instagrapi import Client

cl = Client()
cl.login(USERNAME, PASSWORD)

media = cl.clip_upload(
    Path("reel.mp4"),
    "Uploaded from Pydroid",
    thumbnail=Path("reel-thumb.jpg"),
)
print(media.pk)
```

--------------------------------

### Install instagrapi via pip

Source: https://github.com/subzeroid/instagrapi/blob/master/README.md

Standard installation command for the instagrapi library.

```bash
pip install instagrapi
```

--------------------------------

### Install instagrapi into virtual environment using uv

Source: https://github.com/subzeroid/instagrapi/blob/master/README.md

Command to install the package into the active virtual environment using uv.

```bash
uv pip install instagrapi
```

--------------------------------

### Configure Client with public transport

Source: https://github.com/subzeroid/instagrapi/blob/master/README.md

Example of initializing the Client with specific public transport and impersonation settings.

```python
cl = Client(public_transport="curl", public_transport_impersonate="chrome136")
```

--------------------------------

### cl.bloks_two_step_verification_entrypoint(context)

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/totp.md

Starts the two-step verification flow with the given context.

```APIDOC
## cl.bloks_two_step_verification_entrypoint(context)

### Description
Starts the two-step verification flow with the given context.

### Method
bloks_two_step_verification_entrypoint

### Parameters
- **context** (string) - Required - The two-step verification context from Instagram's login challenge response.

### Request Example
```python
cl.bloks_two_step_verification_entrypoint(context)
```

### Response
- **result** (object) - The response from the entrypoint call.
```

--------------------------------

### Initialize Client and Fetch User Medias

Source: https://github.com/subzeroid/instagrapi/blob/master/README.md

Basic setup to authenticate with a username and password and retrieve recent media for a specific user.

```python
from instagrapi import Client

cl = Client()
cl.login(ACCOUNT_USERNAME, ACCOUNT_PASSWORD)

user_id = cl.user_id_from_username(ACCOUNT_USERNAME)
medias = cl.user_medias(user_id, 20)
```

--------------------------------

### Install optional video helpers

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/termux.md

Installs ffmpeg and the instagrapi video extra. The --no-deps flag is used for MoviePy to prevent downgrading the secure Pillow version.

```bash
pkg install ffmpeg
python -m pip install "instagrapi[video]"
python -m pip install --no-deps "moviepy==2.2.1"
```

--------------------------------

### Install instagrapi with curl extra

Source: https://github.com/subzeroid/instagrapi/blob/master/README.md

Installation command including the optional curl extra for public web TLS impersonation.

```bash
pip install "instagrapi[curl]"
```

--------------------------------

### Install video dependencies

Source: https://github.com/subzeroid/instagrapi/blob/master/README.md

Commands to install optional video processing dependencies, including MoviePy 2.2.1 with specific dependency handling.

```bash
pip install "instagrapi[video]"
pip install --no-deps "moviepy==2.2.1"
```

--------------------------------

### TOTP Workflow Example

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/totp.md

Demonstrates the full workflow of generating a seed, creating a code, enabling 2FA, and disabling it using the Client class.

```python
>>> from instagrapi import Client
>>> cl = Client()
>>> cl.login(USERNAME, PASSWORD)

>>> seed = cl.totp_generate_seed()
"67EIYPWCIJDTTVX632NEODKEU2PY5BIW"

>>> code = cl.totp_generate_code(seed)
"123456"

>>> cl.totp_enable(code)
["1234 5678", "1234 5678", "1234 5678", "1234 5678", "1234 5678"]

>>> cl.totp_disable()
True
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/examples.md

Set these environment variables to provide credentials and session storage paths to the example scripts instead of hard-coding them.

```bash
export IG_USERNAME="your_username"
export IG_PASSWORD="your_password"
export IG_SESSION_FILE="./ig_settings.json"
```

--------------------------------

### Retrieve User Followers, Following, and Info

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/user.md

Examples of fetching follower keys, detailed following lists, and user profile information.

```python
>>> cl.user_followers(cl.user_id).keys()
dict_keys([5563084402, 43848984510, 1498977320, ...])

>>> 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',
      ...
    )
  ),
  ...
}

>>> 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}
```

--------------------------------

### clip_info_for_creation

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/media.md

Gets Reel creation preflight configuration from the mobile API. Returns a dictionary.

```APIDOC
## clip_info_for_creation

### Description
Gets Reel creation preflight configuration from the mobile API. Returns a dictionary.

### Method
clip_info_for_creation

### Signature
clip_info_for_creation()

### Parameters
None

### Returns
- **dict** - Reel creation preflight configuration
```

--------------------------------

### Retrieve user clips

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/media.md

Example of fetching user clips using user_clips_v1 and displaying the dictionary representation of the first result.

```python
>>> clips = cl.user_clips_v1(25025320, amount=2)
>>> clips[0].dict()

{'pk': '3052048407587698594',
 'id': '3052048407587698594_25025320',
 'code': 'CpbDdszj7ei',
 'taken_at': datetime.datetime(2023, 3, 5, 21, 50, 4, tzinfo=datetime.timezone.utc),
 'media_type': 2,
 'product_type': 'clips',
 'thumbnail_url': HttpUrl('https://scontent-den4-1.cdninstagram.com/v/t51.2885-15/333966975_152901010970043_8971338145148712917_n.jpg?stp=dst-jpg_e15_p150x150&_nc_ht=scontent-den4-1.cdninstagram.com&_nc_cat=1&_nc_ohc=rRuJ7u4YrqEAX-UEMFq&edm=ACHbZRIBAAAA&ccb=7-5&ig_cache_key=MzA1MjA0ODQwNzU4NzY5ODU5NA%3D%3D.2-ccb7-5&oh=00_AfC_tNEWVjJLM5RQYUiQJFHQZSmvnDtAcpzs42DRSYt1pQ&oe=6409C451&_nc_sid=4a9e64', scheme='https', host='scontent-den4-1.cdninstagram.com', tld='com', host_type='domain', port='443', path='/v/t51.2885-15/333966975_152901010970043_8971338145148712917_n.jpg', query='stp=dst-jpg_e15_p150x150&_nc_ht=scontent-den4-1.cdninstagram.com&_nc_cat=1&_nc_ohc=rRuJ7u4YrqEAX-UEMFq&edm=ACHbZRIBAAAA&ccb=7-5&ig_cache_key=MzA1MjA0ODQwNzU4NzY5ODU5NA%3D%3D.2-ccb7-5&oh=00_AfC_tNEWVjJLM5RQYUiQJFHQZSmvnDtAcpzs42DRSYt1pQ&oe=6409C451&_nc_sid=4a9e64'),
 'location': {'pk': 213011753,
  'name': 'Sydney, Australia',
  'phone': '',
  'website': '',
  'category': '',
  'hours': {},
  'address': '',
  'city': '',
  'zip': None,
  'lng': 151.20797,
  'lat': -33.86751,
  'external_id': 110884905606108,
  'external_id_source': 'facebook_places'},
....
}
```

--------------------------------

### Search places with cl.fbsearch_places and get location info

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/location.md

Searches for a place by name using Facebook search, then retrieves detailed location info with cl.location_info. The example shows the Place object and the Location object returned by location_info, including fields like pk, name, phone, website, address, and coordinates.

```python
>>> place = cl.fbsearch_places('Perch')[2]
>>> place.dict()
{
 'pk': 3824034,
 'name': 'Perch',
 'phone': '',
 'website': '',
 'category': '',
 'hours': {},
 'address': None,
 'city': None,
 'zip': None,
 'lng': -118.25135,
 'lat': 34.04882,
 'external_id': 207298912632228,
 'external_id_source': 'facebook_places'
}

>>> cl.location_info(place.pk).dict()
{
 'pk': 3824034,
 'name': 'Perch',
 'phone': '(213) 802-1770',
 'website': 'http://www.perchla.com',
 'category': '',
 'hours': {},
 'address': '448 S Hill St',
 'city': 'Los Angeles, California',
 'zip': '90013',
 'lng': -118.25135,
 'lat': 34.04882,
 'external_id': None,
 'external_id_source': None
}
```

--------------------------------

### Upload a story with mentions, links, and hashtags

Source: https://github.com/subzeroid/instagrapi/blob/master/README.md

Demonstrates how to initialize a client, log in with 2FA, download media, and upload it as a story with various interactive elements.

```python
from instagrapi import Client
from instagrapi.types import StoryMention, StoryMedia, StoryLink, StoryHashtag

cl = Client()
cl.login(USERNAME, PASSWORD, verification_code="<2FA CODE HERE>")

media_pk = cl.media_pk_from_url("https://www.instagram.com/p/CGgDsi7JQdS/")
media_path = cl.video_download(media_pk)
subzeroid = cl.user_info_by_username("subzeroid")
hashtag = cl.hashtag_info("dhbastards")

cl.video_upload_to_story(
    media_path,
    "Credits @subzeroid",
    mentions=[StoryMention(user=subzeroid, x=0.49892962, y=0.703125, width=0.8333333333333334, height=0.125)],
    links=[StoryLink(webUri="https://github.com/subzeroid/instagrapi")],
    hashtags=[StoryHashtag(hashtag=hashtag, x=0.23, y=0.32, width=0.5, height=0.22)],
    medias=[StoryMedia(media_pk=media_pk, x=0.5, y=0.5, width=0.6, height=0.8)],
)
```

--------------------------------

### Basic Realtime Receive Loop

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/realtime.md

Demonstrates how to initialize the client, register a generic receive handler, and enter a loop to process incoming MQTT packets.

```python
from instagrapi import Client

cl = Client()
cl.login(USERNAME, PASSWORD)


def handle_receive(event):
    print(event["topic"], event["payload"])


cl.realtime_on("receive", handle_receive)
rt = cl.realtime_connect()

while True:
    cl.realtime_read_once()
```

--------------------------------

### Manage Notes with create_note and get_notes

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/notes.md

Demonstrates creating a note, retrieving all notes, finding a note by username, and deleting a note.

```python
>>> from instagrapi.mixins.note import NoteAudience
>>> note = cl.create_note("Hello from Instagrapi!", audience=NoteAudience.MUTUAL_FOLLOWERS)
>>> print(note.dict())
{'id': '17849203563031468',
'text': 'Hello from Instagrapi!',
'user_id': 12312312312,
'user': {
  'pk': '12312312312',
  'username': 'something',
  'full_name': 'merimi on top',
  'profile_pic_url': HttpUrl('https://scontent-dus1-1.cdninstagram.com/v/t51.2885-19/364347953_6289474204435297_7603222331512295081_n.jpg?stp=dst-jpg_s150x150&_nc_ht=scontent-dus1-1.cdninstagram.com&_nc_cat=101&_nc_ohc=DVaE0MQwn0YAX8-S8dm&edm=AE-H4JwBAAAA&ccb=7-5&oh=00_AfAnH4mHGMl7B5tqzU7b9PMz9qSC4QE_-EX067lwPHnN1w&oe=64DDA1CB&_nc_sid=cff473', ),
  'profile_pic_url_hd': None,
  'is_private': False,
  'stories': []},
'audience': 0,
'created_at': datetime.datetime(2023, 8, 13, 14, 33, 43, tzinfo=datetime.timezone.utc),
'expires_at': datetime.datetime(2023, 8, 14, 14, 33, 43, tzinfo=datetime.timezone.utc),
'is_emoji_only': False,
'has_translation': False,
'note_style': 0}
>>> notes = cl.get_notes()
>>> print(notes)
[Note(id='17849203563031468', text='Hello from Instagrapi, everyone can see it!', ..., has_translation=False, note_style=0), Note(id='17902958207826742', text='Am so happy 💃💃💃💃🙈🤭', ..., has_translation=False, note_style=0)]

>>> cl.get_note_by_user(notes, "something")
Note(id='17849203563031468', text='Hello from Instagrapi, everyone can see it!', ...)

>>> cl.get_note_text_by_user(notes, "something")
'Hello from Instagrapi, everyone can see it!'

>>> cl.last_seen_update_note()

>>> cl.delete_note(note.id)
```

--------------------------------

### Convert media code and URL to media PK

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/media.md

Example usage of media_pk_from_code and media_pk_from_url after logging in. Shows the returned media PKs for given shortcodes and URLs.

```python
>>> from instagrapi import Client
>>> cl = Client()
>>> cl.login(USERNAME, PASSWORD)

>>> 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_pk_from_url("https://www.instagram.com/share/p/BA123456789/")
1787135824035452364
```

--------------------------------

### Initialize Client and Configure Authentication and Proxy

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/interactions.md

Demonstrates logging into an Instagram account, including 2FA and session ID options, and configuring proxy settings for the client.

```python
cl.login("instagrapi", "42")
# cl.login("instagrapi", "42", verification_code="123456")  # with 2FA verification_code
# cl.login_by_sessionid("peiWooShooghahdi2Eip7phohph0eeng")
cl.set_proxy("socks5://127.0.0.1:30235")
# cl.set_proxy("http://YOUR_USERNAME:YOUR_PASSWORD@127.0.0.1:8080")
# cl.set_proxy("socks5://username:password@127.0.0.1:30235")
# when addressing the proxy via hostname:
# cl.set_proxy("socks5h://username:password@exampleproxy.tld:30235")

print(cl.get_settings())
print(cl.user_info(cl.user_id))
```

--------------------------------

### Client Settings Configuration Structure

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/interactions.md

Example of the dictionary structure used to initialize a Client with specific device settings, transport configurations, and session data.

```python
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",
    },
    "authorization_data": {},  # sessionid / ds_user_id / authorization values
    "cookies": {},  # saved cookies
    "last_login": 1596069420.0000145,
    "device_settings": {
        "cpu": "h1",
        "dpi": "640dpi",
        "model": "h1",
        "device": "RS988",
        "resolution": "1440x2392",
        "manufacturer": "LGE/lge",
        "android_release": "6.0.1",
        "android_version": 23,
    },
    "user_agent": "Instagram 385.0.0.47.74 Android (...)",
    "country": "US",
    "country_code": 1,
    "locale": "en_US",
    "timezone_offset": -14400,
    "request_timeout": 1,
    "public_request_retries_count": 3,
    "public_request_retries_timeout": 2,
    "session_retry_total": 3,
    "session_retry_backoff_factor": 2,
    "session_retry_statuses": [429, 500, 502, 503, 504],
    "public_transport": "requests",
    "private_transport": "curl",
    "public_transport_impersonate": "chrome136",
    "tls_verify": True,
}

cl = Client(settings)
```

--------------------------------

### Install instagrapi on Termux

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/termux.md

Updates packages and installs instagrapi using the Termux User Repository to ensure compatible Android wheels for dependencies like pydantic-core.

```bash
pkg update
pkg install python python-pillow
python -m pip install -U pip setuptools wheel
python -m pip install --extra-index-url https://termux-user-repository.github.io/pypi/ instagrapi
```

--------------------------------

### direct_thread_by_participants

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/direct.md

Get thread by user_id.

```APIDOC
## direct_thread_by_participants

### Description
Get thread by user_id.

### Method
SDK Method

### Signature
`direct_thread_by_participants(user_ids: List[int])`

### Parameters
- **user_ids** (List[int]) - Required - List of user IDs.

### Return
DirectThread
```

--------------------------------

### direct_messages

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/direct.md

Get only Messages in Thread.

```APIDOC
## direct_messages

### Description
Get only Messages in Thread.

### Method
SDK Method

### Signature
`direct_messages(thread_id: int, amount: int = 20)`

### Parameters
- **thread_id** (int) - Required - The ID of the thread.
- **amount** (int) - Optional - Number of messages to retrieve. Default: 20.

### Return
List[DirectMessage]
```

--------------------------------

### Initial Login and Session Save

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/best-practices.md

Perform the initial login and save the session settings to a file for future reuse.

```python
from instagrapi import Client

cl = Client()
cl.login(USERNAME, PASSWORD)
cl.dump_settings("session.json")
```

--------------------------------

### direct_thread

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/direct.md

Get Thread with Messages.

```APIDOC
## direct_thread

### Description
Get Thread with Messages.

### Method
SDK Method

### Signature
`direct_thread(thread_id: int, amount: int = 20)`

### Parameters
- **thread_id** (int) - Required - The ID of the thread.
- **amount** (int) - Optional - Number of messages to retrieve. Default: 20.

### Return
DirectThread
```

--------------------------------

### direct_search

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/direct.md

Search threads (for example by username).

```APIDOC
## direct_search

### Description
Search threads (for example by username).

### Method
SDK Method

### Signature
`direct_search(query: str)`

### Parameters
- **query** (str) - Required - Search query.

### Return
List[DirectShortThread]
```

--------------------------------

### direct_channels

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/direct.md

Get Direct channels for a user.

```APIDOC
## direct_channels

### Description
Get Direct channels for a user.

### Method
SDK Method

### Signature
`direct_channels(user_id: Optional[int] = None, thread_subtypes: Optional[List[int]] = None)`

### Parameters
- **user_id** (Optional[int]) - Optional - User ID to get channels for.
- **thread_subtypes** (Optional[List[int]]) - Optional - List of thread subtypes.

### Return
List[Dict]
```

--------------------------------

### Create a Music Note

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/notes.md

Shows the workflow for fetching music candidates and posting a music note.

```python
music = cl.notes_music_browser()
track = music["items"][0]["playlist"]["preview_items"][0]["track"]

note = cl.create_music_note(
    track=track,
    text="",
    audience=NoteAudience.CLOSE_FRIENDS,
    alacorn_session_id=music.get("alacorn_session_id"),
)
cl.delete_note(note.id)
```

--------------------------------

### direct_pending_inbox

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/direct.md

Get all threads from the pending inbox.

```APIDOC
## direct_pending_inbox

### Description
Get all threads from pending inbox.

### Method
SDK Method

### Signature
`direct_pending_inbox(amount: int = 20)`

### Parameters
- **amount** (int) - Optional - Number of threads to retrieve. Default: 20.

### Return
List[DirectThread]
```

--------------------------------

### direct_message

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/direct.md

Get one Message from Thread by id.

```APIDOC
## direct_message

### Description
Get one Message from Thread by id.

### Method
SDK Method

### Signature
`direct_message(thread_id: int, message_id: int, amount: int = 20)`

### Parameters
- **thread_id** (int) - Required - The ID of the thread.
- **message_id** (int) - Required - The ID of the message.
- **amount** (int) - Optional - Number of messages to retrieve. Default: 20.

### Return
DirectMessage
```

--------------------------------

### direct_pending_requests_preview

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/direct.md

Get lightweight pending request counters.

```APIDOC
## direct_pending_requests_preview

### Description
Get lightweight pending request counters.

### Method
SDK Method

### Signature
`direct_pending_requests_preview(pending_inbox_filters: Optional[List[str]] = None)`

### Parameters
- **pending_inbox_filters** (Optional[List[str]]) - Optional - Filters for pending inbox.

### Return
Dict
```

--------------------------------

### Full example: download video and upload to story with mentions, links, hashtags, and media

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/index.md

Logs in with optional 2FA code, downloads a video from a media URL, and uploads it to a story with mentions, a link, hashtags, and a media sticker. Requires the instagrapi types StoryMention, StoryMedia, StoryLink, and StoryHashtag.

```python
from instagrapi import Client
from instagrapi.types import StoryMention, StoryMedia, StoryLink, StoryHashtag

cl = Client()
cl.login(USERNAME, PASSWORD, verification_code="<2FA CODE HERE>")

media_pk = cl.media_pk_from_url("https://www.instagram.com/p/CGgDsi7JQdS/")
media_path = cl.video_download(media_pk)
example = cl.user_info_by_username("example")
hashtag = cl.hashtag_info("dhbastards")

cl.video_upload_to_story(
    media_path,
    "Credits @example",
    mentions=[StoryMention(user=example, x=0.49892962, y=0.703125, width=0.8333333333333334, height=0.125)],
    links=[StoryLink(webUri="https://github.com/subzeroid/instagrapi")],
    hashtags=[StoryHashtag(hashtag=hashtag, x=0.23, y=0.32, width=0.5, height=0.22)],
    medias=[StoryMedia(media_pk=media_pk, x=0.5, y=0.5, width=0.6, height=0.8)],
)
```

--------------------------------

### Send Lightweight Direct Actions via MQTT

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/realtime.md

Examples of publishing Direct actions like sending text, reactions, activity indicators, and seen markers over the MQTT transport.

```python
rt.direct_send_text(thread_id, "Hello from MQTT")
rt.direct_send_reaction(thread_id, item_id, emoji="❤️")
rt.direct_indicate_activity(thread_id, is_active=True)
rt.direct_mark_seen(thread_id, item_id)
```

--------------------------------

### track_info_by_canonical_id(music_canonical_id: str) -> Track

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/track.md

Get track by music_canonical_id.

```APIDOC
## track_info_by_canonical_id(music_canonical_id: str)

### Description
Get track by `music_canonical_id`.

### Method
SDK method

### Parameters
- **music_canonical_id** (str) - Required - The canonical ID of the music track.

### Return
Track object
```

--------------------------------

### media_get_livestream_viewers(broadcast_id: str) -> dict

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/media.md

Gets livestream viewers.

```APIDOC
## media_get_livestream_viewers(broadcast_id: str) -> dict

### Description
Gets livestream viewers.

### Parameters
- **broadcast_id** (str) - Required - The broadcast ID.

### Returns
- **dict** - The viewers data.
```

--------------------------------

### Fetch user media with user_medias_gql and inspect dict

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/media.md

Calls user_medias_gql to fetch one media item for user 1903424587 and prints its dict representation. The output shows the full media object structure including user, usertags, and resources fields.

```python
>>> cl.user_medias_gql(1903424587, amount=1)[0].dict()
{'pk': 2592252466151482347,
 'id': '2592252466151482347_1903424587',
 'code': 'CP5h-I1FuPr',
 'taken_at': datetime.datetime(2021, 6, 9, 12, 9, 56, tzinfo=datetime.timezone.utc),
 'media_type': 8,
 'product_type': '',
 'thumbnail_url': None,
 'location': None,
 'user': {'pk': 1903424587,
  'username': 'example',
  'full_name': '',
  'profile_pic_url': None,
  'profile_pic_url_hd': None,
  'stories': []},
 'comment_count': 5,
 'like_count': 63,
 'has_liked': None,
 'caption_text': 'Любимые подвески ♥️ @daewon1song @tensortrucks',
 'usertags': [{'user': {'pk': 53860445,
    'username': 'tensortrucks',
    'full_name': '',
    'profile_pic_url': None,
    'profile_pic_url_hd': None,
    'stories': []},
   'x': 0.3146666667,
   'y': 0.368159204}],
 'video_url': None,
 'view_count': 0,
 'video_duration': 0.0,
 'title': '',
 'resources': [{'pk': 2592252463089480898,
   'video_url': None,
   'thumbnail_url': HttpUrl('https://instagram.fhel5-1.fna.fbcdn.net/v/t51.2885-15/e35/s1080x1080/198404255_317668533141074_749682826672118306_n.jpg?_nc_ht=instagram.fhel5-1.fna.fbcdn.net&_nc_cat=102&_nc_ohc=f8FR-bZNbp8AX-A6YQ4&edm=APU89FABAAAA&ccb=7-4&oh=864bb145a4fa7e523f5cc22f9ac5d015&oe=61145E4F&_nc_sid=86f79a', scheme='https', host='instagram.fhel5-1.fna.fbcdn.net', tld='net', host_type='domain', path='/v/t51.2885-15/e35/s1080x1080/198404255_317668533141074_749682826672118306_n.jpg', query='_nc_ht=instagram.fhel5-1.fna.fbcdn.net&_nc_cat=102&_nc_ohc=f8FR-bZNbp8AX-A6YQ4&edm=APU89FABAAAA&ccb=7-4&oh=864bb145a4fa7e523f5cc22f9ac5d015&oe=61145E4F&_nc_sid=86f79a'),
   'media_type': 1},
  {'pk': 2592252463081081550,
   'video_url': None,
   'thumbnail_url': HttpUrl('https://instagram.fhel5-1.fna.fbcdn.net/v/t51.2885-15/e35/s1080x1080/198228498_303261361473979_3031095263106513772_n.jpg?_nc_ht=instagram.fhel5-1.fna.fbcdn.net&_nc_cat=107&_nc_ohc=C9SeKrAO6poAX-nXhCG&edm=APU89FABAAAA&ccb=7-4&oh=6aab825e12fef746449be22c322762a1&oe=61132FB0&_nc_sid=86f79a', scheme='https', host='instagram.fhel5-1.fna.fbcdn.net', tld='net', host_type='domain', path='/v/t51.2885-15/e35/s1080x1080/198228498_303261361473979_3031095263106513772_n.jpg', query='_nc_ht=instagram.fhel5-1.fna.fbcdn.net&_nc_cat=107&_nc_ohc=C9SeKrAO6poAX-nXhCG&edm=APU89FABAAAA&ccb=7-4&oh=6aab825e12fef746449be22c322762a1&oe=61132FB0&_nc_sid=86f79a'),
   'media_type': 1},
  {'pk': 2592252463056089912,
   'video_url': None,
   'thumbnail_url': HttpUrl('https://instagram.fhel5-1.fna.fbcdn.net/v/t51.2885-15/e35/s1080x1080/199142152_323583732599636_4553823395468898634_n.jpg?_nc_ht=instagram.fhel5-1.fna.fbcdn.net&_nc_cat=108&_nc_ohc=_feIkorChpsAX_wzTff&edm=APU89FABAAAA&ccb=7-4&oh=a22a2f5b30772fbbb02db92b9394e981&oe=61147D59&_nc_sid=86f79a', scheme='https', host='instagram.fhel5-1.fna.fbcdn.net', tld='net', host_type='domain', path='/v/t51.2885-15/e35/s1080x1080/199142152_323583732599636_4553823395468898634_n.jpg', query='_nc_ht=instagram.fhel5-1.fna.fbcdn.net&_nc_cat=108&_nc_ohc=_feIkorChpsAX_wzTff&edm=APU89FABAAAA&ccb=7-4&oh=a22a2f5b30772fbbb02db92b9394e981&oe=61147D59&_nc_sid=86f79a'),
   'media_type': 1}]}
```

--------------------------------

### media_get_livestream_comments(broadcast_id: str) -> dict

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/media.md

Gets livestream comments.

```APIDOC
## media_get_livestream_comments(broadcast_id: str) -> dict

### Description
Gets livestream comments.

### Parameters
- **broadcast_id** (str) - Required - The broadcast ID.

### Returns
- **dict** - The comments data.
```

--------------------------------

### media_get_livestream_info(broadcast_id: str) -> dict

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/media.md

Gets livestream info.

```APIDOC
## media_get_livestream_info(broadcast_id: str) -> dict

### Description
Gets livestream info.

### Parameters
- **broadcast_id** (str) - Required - The broadcast ID.

### Returns
- **dict** - The livestream info.
```

--------------------------------

### media_user(media_pk: str) -> UserShort

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/media.md

Gets the author of media.

```APIDOC
## media_user(media_pk: str) -> UserShort

### Description
Gets the author of media.

### Parameters
- **media_pk** (str) - Required - The media primary key.

### Returns
- **UserShort** - The author user object.
```

--------------------------------

### Basic login and fetch user media

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/index.md

Logs in with account credentials and retrieves the user ID and recent media for a given username. Replace ACCOUNT_USERNAME and ACCOUNT_PASSWORD with your credentials.

```python
from instagrapi import Client

cl = Client()
cl.login(ACCOUNT_USERNAME, ACCOUNT_PASSWORD)

user_id = cl.user_id_from_username("example")
medias = cl.user_medias(user_id, 20)
```

--------------------------------

### media_start_livestream(broadcast_id: str) -> dict

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/media.md

Starts an existing livestream.

```APIDOC
## media_start_livestream(broadcast_id: str) -> dict

### Description
Starts an existing livestream.

### Parameters
- **broadcast_id** (str) - Required - The broadcast ID.

### Returns
- **dict** - The response dictionary.
```

--------------------------------

### Initialize Client with Private HTTP/2 Transport

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/interactions.md

Initializes the Client with saved settings and a proxy, logs in, and persists the settings to a JSON file.

```python
cl = Client(settings=saved_settings, proxy=proxy_url)
cl.login(username, password)
cl.dump_settings("settings.json")
```

--------------------------------

### login_legacy(username: str, password: str, relogin: bool = False, verification_code: str = "") -> bool

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/interactions.md

Explicit compatibility entry point for the previous login flow.

```APIDOC
## login_legacy(username: str, password: str, relogin: bool = False, verification_code: str = "") -> bool

### Description
Explicit compatibility entry point for the previous login flow.

### Method
login_legacy

### Parameters
- **username** (str) - Required - Instagram username
- **password** (str) - Required - Instagram password
- **relogin** (bool) - Optional - Whether to force re-login (default False)
- **verification_code** (str) - Optional - Verification code (default empty string)

### Return
- **bool** - True if login successful, False otherwise

### Notes
Accepts the same arguments as login().
```

--------------------------------

### direct_requests

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/direct.md

Get message request threads (pending inbox / invitations).

```APIDOC
## direct_requests

### Description
Get message request threads (pending inbox / invitations).

### Method
SDK Method

### Signature
`direct_requests(amount: int = 20)`

### Parameters
- **amount** (int) - Optional - Number of threads to retrieve. Default: 20.

### Return
List[DirectThread]
```

--------------------------------

### archive_stories(amount: int = 0) -> List[Story]

Source: https://github.com/subzeroid/instagrapi/blob/master/docs/usage-guide/story.md

Get your archived stories.

```APIDOC
## archive_stories(amount: int = 0)

### Description
Get your archived stories.

### Parameters
- **amount** (int) - Optional - The number of archived stories to retrieve.

### Returns
- **List[Story]** - A list of Story objects.
```
Tokens:
Raw