### Get User Guides (v1)

Source: https://subzeroid.github.io/instagrapi/usage-guide/user.html

Retrieves a list of guides created by a specific user.

```APIDOC
## GET /user_guides_v1

### Description
Get user’s guides.

### Method
GET

### Parameters
#### Query Parameters
- **user_id** (int) - Required - The ID of the user whose guides to retrieve.
```

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

### Fetch User Media (GQL)

Source: https://subzeroid.github.io/instagrapi/usage-guide/media.html

Fetches user media using the GraphQL interface. This example shows how to get the first media item and display its dictionary representation.

```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': 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',
   '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',
   'media_type': 1},
  {'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',
   'media_type': 1}]}

```

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

### v2 SERP Endpoints Examples

Source: https://subzeroid.github.io/instagrapi/usage-guide/search.html

Demonstrates how to fetch paginated search results from different v2 SERP endpoints for top, accounts, and reels tabs. Includes examples for fetching the first page and subsequent pages using pagination tokens.

```Python
# Top tab — first page
top = cl.fbsearch_topsearch_v2("python")

# Accounts — paginate
page1 = cl.fbsearch_accounts_v2("python")
page2 = cl.fbsearch_accounts_v2("python", page_token=page1["next_page_token"])

# Reels — paginate
page1 = cl.fbsearch_reels_v2("python")
page2 = cl.fbsearch_reels_v2("python", reels_max_id=page1["reels_max_id"])

# Typeahead — flat list of user dicts
users = cl.fbsearch_typehead("py")

# Top media — typed Media objects
medias = cl.media_search("python", amount=3)

```

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

### Install Dependencies for Story Music Upload

Source: https://subzeroid.github.io/instagrapi/usage-guide/story.html

Installs the necessary libraries for uploading stories with music. This includes the instagrapi package with video support and the moviepy library.

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

```

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

### Install pre-commit with pipx

Source: https://subzeroid.github.io/instagrapi/development-guide.html

Installs the pre-commit tool globally using pipx if you prefer to keep it outside the project environment.

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

```

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

### Get Music Canonical IDs from Reels

Source: https://subzeroid.github.io/instagrapi/usage-guide/track.html

This example demonstrates how to retrieve the music_canonical_id for the first 10 reels. Ensure you have logged in with your USERNAME and PASSWORD before executing.

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

>>> [media.clips_metadata['music_canonical_id'] for media in cl.reels(amount=10)]

['18159860503036324',
 '18245182426110798',
 '18156435169051995',
 '18274086877034385',
 '18243482860109137',
 '18244791958105000',
 '18310451203035205',
 '18293984647065921',
 '18154598032011335',
 '18301950994013617']
```

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

### Install Instagrapi

Source: https://subzeroid.github.io/instagrapi/getting-started.html

Install the instagrapi library using pip. Ensure you are using Python 3.10+.

```bash
python -m pip install instagrapi

```

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

### Install Instagrapi Video Dependencies

Source: https://subzeroid.github.io/instagrapi/usage-guide/pydroid.html

Install the optional video extra for instagrapi and MoviePy. Use --no-deps for MoviePy to maintain a compatible Pillow version.

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

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

### Install instagrapi on Termux

Source: https://subzeroid.github.io/instagrapi/usage-guide/termux.html

Installs Python, Pillow for image handling, and instagrapi with necessary wheels from the Termux User Repository. Pillow is recommended to be installed via pkg to avoid slow source builds.

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

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

### clip_info_for_creation

Source: https://subzeroid.github.io/instagrapi/usage-guide/media.html

Get Reel creation preflight configuration from the mobile API.

```APIDOC
## clip_info_for_creation

### Description
Get Reel creation preflight configuration from the mobile API.

### Method
`clip_info_for_creation()`
```

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

### Install Optional Video Helpers in Termux

Source: https://subzeroid.github.io/instagrapi/usage-guide/termux.html

Installs ffmpeg and the 'video' extra for instagrapi, along with MoviePy, for advanced video functionalities like automatic thumbnail generation and video composition. Uses --no-deps for MoviePy to maintain a compatible Pillow version.

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

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

### Set up Local Environment with uv

Source: https://subzeroid.github.io/instagrapi/development-guide.html

Installs the library and development dependencies using uv, ensuring pyproject.toml remains the source of truth.

```bash
uv venv
source .venv/bin/activate
uv pip install -e ".[test]"
pre-commit install

```

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

### Set up Local Environment with venv

Source: https://subzeroid.github.io/instagrapi/development-guide.html

Installs the library, runtime dependencies, test tools, lint tools, and documentation tooling in a virtual environment.

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

```

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

### Get User Following List

Source: https://subzeroid.github.io/instagrapi/usage-guide/user.html

Fetches a dictionary of users that the target user is following. Each entry contains detailed UserShort objects.

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

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

### Login and Fetch User Media

Source: https://subzeroid.github.io/instagrapi

Demonstrates basic client initialization, login, and fetching a user's recent media. Ensure ACCOUNT_USERNAME and ACCOUNT_PASSWORD are set.

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

```

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

### Get Direct Thread by Participants

Source: https://subzeroid.github.io/instagrapi/usage-guide/direct.html

Use `direct_thread_by_participants` to retrieve a direct message thread based on a list of participant user IDs. This is useful for finding or starting conversations with specific users.

```python
>>> cl.direct_thread_by_participants([cl.user_id])
DirectThread(pk=178612312342, id=340282366812312312312341298762, messages=[DirectMessage(id=30076214123123123123123864, user_id=1903424587, thread_id=None, timestamp=datetime.datetime(2021, 8, 31, 18, 33, 49, 107154, ...)
```

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

### Install Curl Transport for Instagrapi

Source: https://subzeroid.github.io/instagrapi/usage-guide/public-transport.html

Install the optional curl transport for Instagrapi to handle public web endpoints that may be rate-limited or blocked by TLS fingerprint checks. This requires installing the package with the 'curl' extra.

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

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

### Instagrapi Client Login and Basic Actions

Source: https://subzeroid.github.io/instagrapi/usage-guide/direct.html

Shows how to initialize the Instagrapi client, log in with credentials, and perform basic actions like retrieving the first direct thread and accessing its properties.

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

>>> thread = cl.direct_threads(1)[0]
>>> thread.pk
18123276039123479

>>> thread.users
[UserShort(pk=123123123, username='something', full_name='Dima Something', profile_pic_url=HttpUrl('https://instagram.frix7-1.fna.fbcdn.net/v/t51.2885-19/s150x150/11374323_1630877790512376_1081658215_a.jpg?_nc_ht=instagram.frix7-1.fna.fbcdn.net&_nc_ohc=k22oMvVv8xEAX-UEVRB&edm=AI8ESKwBAAAA&ccb=7-4&oh=be799948b28f19d85158153d886d16d3&oe=6135D80F&_nc_sid=195af5', scheme='https', host='instagram.frix7-1.fna.fbcdn.net', tld='net', host_type='domain', path='/v/t51.2885-19/s150x150/11374323_1630877790512376_1081658215_a.jpg', query='_nc_ht=instagram.frix7-1.fna.fbcdn.net&_nc_ohc=k22oMvVv8xEAX-UEVRB&edm=AI8ESKwBAAAA&ccb=7-4&oh=be799948b28f19d85158153d886d16d3&oe=6135D80F&_nc_sid=195af5'), profile_pic_url_hd=None, is_private=False, stories=[])]

>>> thread.messages[0]
DirectMessage(id=300761992574947211231231241955932160, user_id=123123123, thread_id=None, timestamp=datetime.datetime(2021, 8, 31, 18, 20, 28, 754135, tzinfo=datetime.timezone.utc), item_type='text', is_shh_mode=False, reactions=None, text='Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua', animated_media=None, media=None, media_share=None, reel_share=None, story_share=None, felix_share=None, clip=None, placeholder=None)

```

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

### Realtime Client Connection and Event Handling

Source: https://subzeroid.github.io/instagrapi/usage-guide/realtime.html

Connect to the Realtime MQTT client, register a general receive handler, and enter a loop to process incoming events.

```APIDOC
## Realtime Client Connection and Event Handling

### Description
Connect to the Realtime MQTT client, register a general receive handler, and enter a loop to process incoming events.

### Method
`realtime_connect()`

### Parameters
- `transport` (str, optional): The transport protocol to use. Defaults to None.

### Return
`RealtimeClient` object

### Example
```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()
```
```

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

### Get Story Archive Days

Source: https://subzeroid.github.io/instagrapi/usage-guide/story.html

Retrieve a list of `StoryArchiveDay` objects for the logged-in account's story archive. Use `archive_stories()` to get the actual media items from these days.

```python
days = client.archive_story_days()

```

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

### Send Lightweight Direct Actions over MQTT

Source: https://subzeroid.github.io/instagrapi/usage-guide/realtime.html

Demonstrates sending lightweight direct messages, reactions, activity indicators, and mark-seen states over MQTT. Use these for simple, real-time interactions.

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

```

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

### Media Author

Source: https://subzeroid.github.io/instagrapi/usage-guide/media.html

Get the author of a media item.

```APIDOC
## media_user
### Description
Get author of media
### Method
media_user(media_pk: str) -> UserShort
```

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

### Client Initialization and Basic Interactions

Source: https://subzeroid.github.io/instagrapi/usage-guide/interactions.html

Initialize the instagrapi client with optional settings and perform basic actions like login, setting proxies, and retrieving user information.

```APIDOC
## Client Initialization

### Description
Initializes the instagrapi client with optional settings, proxy, and TLS verification.

### Method
`Client(settings: dict = {}, proxy: str = "", tls_verify: Union[bool, str] = True)`

### Parameters
- **settings** (dict) - Optional - Dictionary containing client settings.
- **proxy** (str) - Optional - Proxy server URL.
- **tls_verify** (Union[bool, str]) - Optional - TLS certificate verification setting.

## Login Methods

### Description
Provides various methods for logging into an Instagram account, including username/password, 2FA, session ID, and relogin.

### Methods
- **login(username: str, password: str)**
  - **Return**: bool
  - **Description**: Login by username and password. Gets new cookies if they don't exist in settings.
- **login(username: str, password: str, verification_code: str)**
  - **Return**: bool
  - **Description**: Login by username and password with a 2FA verification code (TOTP, not SMS).
- **relogin()**
  - **Return**: bool
  - **Description**: Re-login with clean cookies. Requires `cl.username` and `cl.password` to be set.
- **login_by_sessionid(sessionid: str)**
  - **Return**: bool
  - **Description**: Lightweight login using a session cookie value. Works when Instagram accepts the session ID for the private mobile API.
- **inject_sessionid_to_public()**
  - **Return**: bool
  - **Description**: Inject session ID from a Private Session to a Public Session.
- **logout()**
  - **Return**: bool
  - **Description**: Logs out the current user session.

### Usage Examples
```python
from instagrapi import Client

cl = Client()

# Login with username and password
cl.login("instagrapi", "42")

# Login with username, password, and 2FA code
# cl.login("instagrapi", "42", verification_code="123456")

# Login using a session ID
# cl.login_by_sessionid("peiWooShooghahdi2Eip7phohph0eeng")

# Set proxy
cl.set_proxy("socks5://127.0.0.1:30235")
# cl.set_proxy("http://username:password@127.0.0.1:8080")
# cl.set_proxy("socks5://username:password@127.0.0.1:30235")
# cl.set_proxy("socks5h://username:password@exampleproxy.tld:30235")

# Get settings and user info
print(cl.get_settings())
print(cl.user_info(cl.user_id))
```

## Client Settings

### Description
Configurable properties for the instagrapi client that affect request handling and transport behavior.

### Properties
- **request_logger** (Logger) - Logger for registering various Instagram actions.
- **request_timeout** (int) - Timeout in seconds between requests (default: 1).
- **public_request_retries_count** (int) - Default retry count for `public_request()`.
- **public_request_retries_timeout** (int) - Delay in seconds between `public_request()` retries.
- **session_retry_total** (int) - Transport-level retry count for `public` and `private` sessions.
- **session_retry_backoff_factor** (int) - Backoff factor for transport-level retries.
- **public_transport** (str) - Public web transport mechanism (`requests` or `curl`).
- **public_transport_impersonate** (str) - Browser fingerprint for the `curl` public transport.
- **tls_verify** (Union[bool, str]) - TLS certificate verification setting (`True`, `False`, or CA bundle path).

### Example Settings Dictionary
```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": {},
   "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",
   "public_transport_impersonate": "chrome136",
   "tls_verify": True
}

cl = Client(settings)
```
```

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

### Direct Search

Source: https://subzeroid.github.io/instagrapi/usage-guide/direct.html

Searches for threads, for example by username.

```APIDOC
## direct_search

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

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

### Return Type
List[DirectShortThread]
```

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

### Login and Proxy Configuration

Source: https://subzeroid.github.io/instagrapi/usage-guide/interactions.html

Demonstrates logging into an Instagram account with username and password, setting proxy details, and retrieving client settings and user information. Includes commented-out examples for 2FA login and different proxy formats.

```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://username: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 Initialization with Settings

Source: https://subzeroid.github.io/instagrapi/usage-guide/interactions.html

Initializes the Instagrapi client using a predefined settings dictionary, which includes user agent, device settings, proxy configurations, and retry parameters. This is useful for reusing saved 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",
   "public_transport_impersonate": "chrome136",
   "tls_verify": True
}

cl = Client(settings)
```

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

### Get Archived Stories

Source: https://subzeroid.github.io/instagrapi/usage-guide/story.html

Retrieves a list of your archived stories.

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

### Description
Get your archived stories.

### Parameters
#### Path Parameters
- **amount** (int) - Optional - The maximum number of archived stories to retrieve. Defaults to 0 (all).

### Return
List[Story]
```

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

### clip_share_to_fb_config

Source: https://subzeroid.github.io/instagrapi/usage-guide/media.html

Get Reel Facebook sharing configuration from the mobile API.

```APIDOC
## clip_share_to_fb_config

### Description
Get Reel Facebook sharing configuration from the mobile API.

### Method
`clip_share_to_fb_config()`
```

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

### clip_share_to_fb_unified_config

Source: https://subzeroid.github.io/instagrapi/usage-guide/media.html

Get the Android cross-posting unified config used by the Reel composer.

```APIDOC
## clip_share_to_fb_unified_config

### Description
Get the Android cross-posting unified config used by the Reel composer.

### Method
`clip_share_to_fb_unified_config()`
```

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

### Build and Upload Video Story

Source: https://subzeroid.github.io/instagrapi/usage-guide/story.html

Use StoryBuilder to create a video story with mentions and a background. The video is then uploaded using cl.video_upload_to_story.

```python
from instagrapi.types import StoryMention, StoryMedia, StoryLink
from instagrapi.story import StoryBuilder

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

buildout = StoryBuilder(
    media_path,
    'Credits @example',
    [StoryMention(user=example)],
    Path('/path/to/background_720x1280.jpg')
).video(15)  # seconds

cl.video_upload_to_story(
    buildout.path,
    "Credits @example",
    mentions=buildout.mentions,
    links=[StoryLink(webUri='https://github.com/subzeroid/instagrapi')],
    medias=[StoryMedia(media_pk=media_pk)]
)
```

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

### Direct Pending Requests Preview

Source: https://subzeroid.github.io/instagrapi/usage-guide/direct.html

Gets lightweight counters for pending requests.

```APIDOC
## direct_pending_requests_preview

### Description
Get lightweight pending request counters.

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

### Return Type
Dict
```

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

### Subscribe to Raw Realtime Topics

Source: https://subzeroid.github.io/instagrapi/usage-guide/realtime.html

Use `rt.graph_ql_subscribe` and `rt.skywalker_subscribe` to subscribe to raw GraphQL and Skywalker topics. These subscription strings are advanced and unstable.

```python
rt.graph_ql_subscribe(["<graphql-subscription>"])
rt.skywalker_subscribe(["<skywalker-subscription>"])

```

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

### Get Recent Hashtag Media

Source: https://subzeroid.github.io/instagrapi/usage-guide/hashtag.html

Retrieves the most recent posts for a specified hashtag.

```APIDOC
## hashtag_medias_recent(name: str, amount: int = 27)

### Description
Return recent posts for a hashtag.

### Method
`hashtag_medias_recent`

### Parameters
#### Path Parameters
- **name** (str) - Required - The name of the hashtag (without '#').
- **amount** (int) - Optional - The number of recent posts to retrieve. Defaults to 27.

### Return
List[Media] - A list of media objects representing the recent posts.
```

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

### Get replies to a comment

Source: https://subzeroid.github.io/instagrapi/usage-guide/comment.html

Retrieve replies made to a specific comment on a media.

```APIDOC
## GET /media_comment_replies

### Description
Fetches all replies associated with a specific parent comment on a given media item.

### Method
GET

### Endpoint
`/media_comment_replies`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **media_id** (string) - Required - The ID of the media containing the comment.
- **parent_comment_id** (string) - Required - The ID of the parent comment whose replies are to be retrieved.

### Request Example
```python
parent_comment = cl.media_comments(media_id)[0]
replies = cl.media_comment_replies(media_id, parent_comment.pk)
```

### Response
#### Success Response (200)
Returns a list of comment objects representing the replies.

#### Response Example
```json
[
  {
    "pk": 17926777897585110,
    "text": "Reply text",
    "user": { ... },
    "created_at_utc": "2021-05-15T14:51:03Z",
    "content_type": "comment",
    "status": "Active",
    "replied_to_comment_id": "17926777897585108",
    "has_liked": false,
    "like_count": 0
  }
]
```
```

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

### Paginated User Media Fetch

Source: https://subzeroid.github.io/instagrapi/usage-guide/media.html

Demonstrates how to fetch user media in pages using a stored cursor to resume fetching. This is useful for retrieving large numbers of media items.

```python
>>> end_cursor = None
... for page in range(3):
...     medias, end_cursor = client.user_medias_paginated(1903424587, 5, end_cursor=end_cursor)
...     print([ m.taken_at.date().isoformat() for m in medias ])
... 
['2021-06-09', '2019-10-16', '2019-10-14', '2019-06-13', '2019-06-06']
['2019-06-05', '2019-03-23', '2019-03-23', '2018-11-15', '2018-10-16']
['2018-10-16', '2018-10-11', '2018-10-09', '2018-10-09', '2018-08-02']

```

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

### Livestream Management

Source: https://subzeroid.github.io/instagrapi/usage-guide/media.html

Methods for creating, starting, ending, and retrieving information about livestreams.

```APIDOC
## media_create_livestream
### Description
Create a new livestream and return stream metadata
### Method
media_create_livestream(title: str = "Instagram Live") -> dict

## media_start_livestream
### Description
Start an existing livestream
### Method
media_start_livestream(broadcast_id: str) -> dict

## media_end_livestream
### Description
End an existing livestream
### Method
media_end_livestream(broadcast_id: str) -> dict

## media_get_livestream_info
### Description
Get livestream info
### Method
media_get_livestream_info(broadcast_id: str) -> dict

## media_get_livestream_comments
### Description
Get livestream comments
### Method
media_get_livestream_comments(broadcast_id: str) -> dict

## media_get_livestream_viewers
### Description
Get livestream viewers
### Method
media_get_livestream_viewers(broadcast_id: str) -> dict
```

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

### Create and Retrieve Text Notes

Source: https://subzeroid.github.io/instagrapi/usage-guide/notes.html

Demonstrates creating a new text Note with a specified audience and then retrieving all Notes. Use `NoteAudience.MUTUAL_FOLLOWERS` for followers you follow back or `NoteAudience.CLOSE_FRIENDS` for Close Friends only. Notes should not exceed 60 characters, and requests should be spaced at least 2 minutes apart.

```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)]
```

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

### Create Music Note

Source: https://subzeroid.github.io/instagrapi/usage-guide/notes.html

This snippet illustrates how to create a Note with music. It involves first browsing for music candidates using `notes_music_browser()`, selecting a track, and then using `create_music_note()` with the chosen track and desired audience. The `alacorn_session_id` can be passed from the music browser response.

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

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

### Get Direct Thread

Source: https://subzeroid.github.io/instagrapi/usage-guide/direct.html

Retrieves a direct message thread with a specified amount of messages.

```APIDOC
## GET direct_thread

### Description
Retrieves a specific direct message thread, fetching a specified number of recent messages.

### Method
GET

### Endpoint
`/direct_thread` (This is a conceptual representation based on the SDK method)

### Parameters
#### Path Parameters
- **thread_id** (string) - Required - The ID of the thread to retrieve.

#### Query Parameters
- **amount** (integer) - Optional - The number of recent messages to fetch. Defaults to a reasonable amount if not specified.

### Response
#### Success Response (200)
- **DirectThread** (object) - Contains details of the direct thread.
  - **pk** (string) - The primary key of the thread.
  - **id** (string) - The unique identifier for the thread.
  - **messages** (array) - A list of messages within the thread.

### Request Example
```python
cl.direct_thread(thread_id, amount=1)
```

### Response Example
```json
{
  "pk": "178612312342",
  "id": "340282366812312312312341298762",
  "messages": [
    {
      "id": "30076214123123123123123864",
      "user_id": "1903424587",
      "thread_id": null,
      "timestamp": "2021-08-31T18:33:49.107154+00:00",
      "item_type": null,
      "is_shh_mode": null,
      "reactions": null,
      "text": null,
      "animated_media": null,
      "media": null,
      "media_share": null,
      "reel_share": null,
      "story_share": null,
      "felix_share": null,
      "clip": null,
      "placeholder": null
    }
  ],
  ...
}
```
```

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

### Get Direct Thread by Participants

Source: https://subzeroid.github.io/instagrapi/usage-guide/direct.html

Retrieves a direct thread based on the participants involved.

```APIDOC
## GET direct_thread_by_participants

### Description
Retrieves a direct message thread identified by its participants.

### Method
GET

### Endpoint
`/direct_thread_by_participants` (This is a conceptual representation based on the SDK method)

### Parameters
#### Query Parameters
- **user_ids** (array of strings) - Required - A list of user IDs that are participants in the thread.

### Response
#### Success Response (200)
- **DirectThread** (object) - Contains details of the direct thread.
  - **pk** (string) - The primary key of the thread.
  - **id** (string) - The unique identifier for the thread.
  - **messages** (array) - A list of messages within the thread.

### Request Example
```python
cl.direct_thread_by_participants([cl.user_id])
```

### Response Example
```json
{
  "pk": "178612312342",
  "id": "340282366812312312312341298762",
  "messages": [
    {
      "id": "30076214123123123123123864",
      "user_id": "1903424587",
      "thread_id": null,
      "timestamp": "2021-08-31T18:33:49.107154+00:00",
      "item_type": null,
      "is_shh_mode": null,
      "reactions": null,
      "text": null,
      "animated_media": null,
      "media": null,
      "media_share": null,
      "reel_share": null,
      "story_share": null,
      "felix_share": null,
      "clip": null,
      "placeholder": null
    }
  ]
}
```
```

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

### Configure TLS Verification with CA Certificate

Source: https://subzeroid.github.io/instagrapi/usage-guide/interactions.html

Install a trusted local debugging proxy's CA certificate and point the client at that bundle to enable TLS verification.

```python
cl = Client(tls_verify="/path/to/proxy-ca.pem")
```

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

### Load Session and Login

Source: https://subzeroid.github.io/instagrapi/getting-started.html

Load previously saved session settings and log in. This is the recommended approach for subsequent runs to avoid repeated password entry.

```python
from instagrapi import Client

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

```

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

### Get Direct Message

Source: https://subzeroid.github.io/instagrapi/usage-guide/direct.html

Retrieves a specific direct message by its thread and message ID.

```APIDOC
## GET direct_message

### Description
Retrieves details of a specific direct message within a thread.

### Method
GET

### Endpoint
`/direct_message` (This is a conceptual representation based on the SDK method)

### Parameters
#### Path Parameters
- **thread_id** (string) - Required - The ID of the thread containing the message.
- **message_id** (string) - Required - The ID of the message to retrieve.

### Response
#### Success Response (200)
- **DirectMessage** (object) - Contains details of the direct message.
  - **id** (string) - The unique identifier for the message.
  - **user_id** (string) - The ID of the user who sent the message.
  - **thread_id** (string) - The ID of the thread the message belongs to.
  - **timestamp** (datetime) - The time the message was sent.
  - **item_type** (string) - The type of the message content (e.g., 'text').
  - **is_shh_mode** (boolean) - Indicates if the message was sent in 'shh' mode.
  - **reactions** (array) - List of reactions to the message.
  - **text** (string) - The text content of the message.
  - **animated_media** (object) - Details of any animated media attached.
  - **media** (object) - Details of any media attached.
  - **media_share** (object) - Details of any media share.
  - **reel_share** (object) - Details of any reel share.
  - **story_share** (object) - Details of any story share.
  - **felix_share** (object) - Details of any Felix share.
  - **clip** (object) - Details of any clip.
  - **placeholder** (object) - Placeholder information.

### Request Example
```python
cl.direct_message(thread.id, message.id)
```

### Response Example
```json
{
  "id": "300712312341231237412312312360",
  "user_id": "12312312",
  "thread_id": null,
  "timestamp": "2021-08-31T18:20:28.075413+00:00",
  "item_type": "text",
  "is_shh_mode": false,
  "reactions": null,
  "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua",
  "animated_media": null,
  "media": null,
  "media_share": null,
  "reel_share": null,
  "story_share": null,
  "felix_share": null,
  "clip": null,
  "placeholder": null
}
```
```

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

### Get Followed Hashtags

Source: https://subzeroid.github.io/instagrapi/usage-guide/hashtag.html

Retrieves a list of hashtags that the authenticated account is currently following.

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

### Description
Return hashtags followed by the authenticated account.

### Method
`hashtag_following`

### Parameters
#### Path Parameters
- **amount** (int) - Optional - The maximum number of followed hashtags to return. If 0, returns all. Defaults to 0.

### Return
List[Hashtag] - A list of Hashtag objects representing the followed hashtags.
```

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

### Get Top Hashtag Media

Source: https://subzeroid.github.io/instagrapi/usage-guide/hashtag.html

Fetches the top posts associated with a given hashtag.

```APIDOC
## hashtag_medias_top(name: str, amount: int = 9)

### Description
Return top posts for a hashtag.

### Method
`hashtag_medias_top`

### Parameters
#### Path Parameters
- **name** (str) - Required - The name of the hashtag (without '#').
- **amount** (int) - Optional - The number of top posts to retrieve. Defaults to 9.

### Return
List[Media] - A list of media objects representing the top posts.
```

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

### Share Media to Story

Source: https://subzeroid.github.io/instagrapi/usage-guide/media.html

Shows how to share a media item to a user's story. It first retrieves the media's primary key from its URL and then performs the share operation.

```python
>>> media_pk = cl.media_pk_from_url("https://www.instagram.com/p/CGgDsi7JQdS/")
>>> story = cl.media_share_to_story(media_pk)
>>> story.pk
'3155832952940083788'

```

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

### Search Music

Source: https://subzeroid.github.io/instagrapi/usage-guide/track.html

Search for music tracks using a query string. This example demonstrates searching for tracks related to 'love' and retrieving the first result.

```python
>>> cl.search_music("love")[0].dict()
{
'id': '354372829354341',
'title': 'Love Your Voice',
'subtitle': '',
'display_artist': 'JONY',
'audio_cluster_id': 410742646320351,
'artist_id': None,
'cover_artwork_uri': HttpUrl('https://cdn.fbsbx.com/v/t65.14500-21/191897578_1074647849725858_3973554110966662866_n.jpg?stp=cp0_dst-jpg_e15_p526x296_q65&_nc_cat=1&ccb=1-7&_nc_sid=cbead8&_nc_ohc=ugygksMclf4AX_u7L7g&_nc_ht=cdn.fbsbx.com&oh=00_AT89FBXl6h7Q6zytlI5cA4UIG_zQkK_DsOqyUqyXk1zyIg&oe=62DAEA82', scheme='https', host='cdn.fbsbx.com', tld='com', host_type='domain', port='443', path='/v/t65.14500-21/191897578_1074647849725858_3973554110966662866_n.jpg', query='stp=cp0_dst-jpg_e15_p526x296_q65&_nc_cat=1&ccb=1-7&_nc_sid=cbead8&_nc_ohc=ugygksMclf4AX_u7L7g&_nc_ht=cdn.fbsbx.com&oh=00_AT89FBXl6h7Q6zytlI5cA4UIG_zQkK_DsOqyUqyXk1zyIg&oe=62DAEA82'),
}
```

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

### Get User Highlights

Source: https://subzeroid.github.io/instagrapi/usage-guide/highlight.html

Fetches a list of all highlights associated with a specific user ID.

```APIDOC
## user_highlights

### Description
Get a user’s highlights.

### Method
`user_highlights(user_id: str, amount: int = 0)`

### Parameters
#### Path Parameters
- **user_id** (str) - Required - The ID of the user whose highlights to retrieve.
- **amount** (int) - Optional - The maximum number of highlights to retrieve. Defaults to 0 (all highlights).

### Return
- **List[Highlight]** - A list of highlight objects.
```