Instagrapi

https://subzeroid.github.io/instagrapi/
Admin
Instagrapi is a fast and powerful Python library for Instagram Private API that enables public and...
Tokens:71,554
Snippets:606
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### TOTP Workflow Example

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

Demonstrates the full lifecycle of TOTP setup, code generation, enabling 2FA, and disabling it.

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

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

### 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 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 via pip

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

Use this command to install the library in your Python environment.

```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 Dependencies for Music Uploads

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

Required packages for enabling story music upload functionality.

```bash
pip install "instagrapi[video]"
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

```

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

### Configure Notification Settings

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

Example demonstrating how to update specific notification settings and mute all notifications.

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

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

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

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

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

```

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

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

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

### Install and Enable Curl Transport

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

Install the optional curl transport and enable it for public web endpoints to improve TLS fingerprint compatibility.

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

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

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

### Retrieve User Data and Relationships

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

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

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

### Retrieve Timeline and Reels Feeds

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

Examples for fetching timeline feeds with pagination and retrieving various reels categories.

```python
>>> first_page = cl.get_timeline_feed("cold_start_fetch")
>>> second_page = cl.get_timeline_feed(max_id=first_page["next_max_id"])
>>> cl.reels(amount=10)
>>> cl.explore_reels(amount=10)
>>> cl.friends_reels(amount=10)
```

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

### 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]"
```

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

### media_info_v1(media_pk: str)

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

Get media from PK via private mobile API.

```APIDOC
## media_info_v1(media_pk: str)

### Description
Get media from PK via private mobile API.

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

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

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

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

### Livestream Management

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

Methods for creating, starting, ending, and monitoring Instagram livestreams.

```APIDOC
## Livestream Management

- `media_create_livestream(title: str = "Instagram Live") -> dict`: Create a new livestream.
- `media_start_livestream(broadcast_id: str) -> dict`: Start an existing livestream.
- `media_end_livestream(broadcast_id: str) -> dict`: End an existing livestream.
- `media_get_livestream_info(broadcast_id: str) -> dict`: Get livestream info.
```

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

### Implement Request Fallback Logic

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

Example of a pattern to attempt a public GraphQL request first and fall back to a private API request if an error occurs.

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

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

### Get Highlight Information

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

Retrieves detailed information about a specific highlight using its primary key (PK) or ID.

```APIDOC
## highlight_info

### Description
Get highlight by PK or ID.

### Method
`highlight_info(highlight_pk: str)`

### Parameters
#### Path Parameters
- **highlight_pk** (str) - Required - The primary key or ID of the highlight.

### Return
- **Highlight** - An object containing highlight details.
```

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

### Basic Realtime MQTT Receive Loop

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

Connect to Instagram's Realtime MQTT, register a handler for incoming events, and continuously read packets. This is a fundamental example for receiving live data.

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

```

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

### Minimal Instagrapi Clip Upload

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

A basic example of uploading a clip using instagrapi, requiring login credentials and specifying the video and thumbnail paths.

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

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

### Set Environment Variables for Instagrapi

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

Set environment variables for Instagram username, password, and session file before running examples. This avoids hard-coding sensitive information.

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

```

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

### Initialize Client and Fetch User Media

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

Demonstrates basic client authentication and retrieving 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("example")
medias = cl.user_medias(user_id, 20)
```

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

### media_info_gql(media_pk: str)

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

Get media from PK via public GraphQL API. Falls back from legacy query_hash to the newer doc_id media query when available.

```APIDOC
## media_info_gql(media_pk: str)

### Description
Get media from PK via public GraphQL API. Falls back from legacy query_hash to the newer doc_id media query when available.

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

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

### Get Location Information

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

Fetches detailed information for a specific location using its primary key. Note that some fields like 'address' might be empty.

```python
>>> location = cl.location_info(107617247320879)
>>> location.dict()
{'pk': 107617247320879,
 'name': 'Russia, Saint-Petersburg',
 'address': '',
 'lng': 30.30605,
 'lat': 59.93318,
 'external_id': None,
 'external_id_source': None}
```

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

### Paginate Hashtag Media (GraphQL)

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

Fetch a page of recent media for a hashtag using the public GraphQL API. Use the returned cursor for subsequent requests to get more media.

```python
>>> medias, cursor = cl.hashtag_medias_paginated('test', amount=32, tab_key='recent')
```

```python
>>> next_medias, cursor = cl.hashtag_medias_paginated('test', amount=32, tab_key='recent', end_cursor=cursor)
```

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

### user_medias_gql(user_id: str, amount: int = 0, sleep: int = 0)

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

Get user media via public GraphQL API.

```APIDOC
## user_medias_gql(user_id: str, amount: int = 0, sleep: int = 0)

### Description
Get user media via public GraphQL API.

### Parameters
- **user_id** (str) - Required - The ID of the user.
- **amount** (int) - Optional - Number of items to retrieve.
- **sleep** (int) - Optional - Sleep time between requests.
```

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

### Initialize Client and Configure Authentication

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

Demonstrates logging into an Instagram account using credentials or session IDs and configuring proxy settings.

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

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

### Define and Load Client Settings

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

Shows the structure of the settings dictionary used to persist session data and device configuration, and how to pass it to the Client constructor.

```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 Top Medias from Location

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

Retrieves the top media items from a specified location ID. The result is a list of media objects, and the first item's dictionary representation is shown.

```python
>>> medias = cl.location_medias_top(107617247320879, amount=2)
>>> medias[0].dict()
```

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

### Perform basic direct messaging actions

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

Initialize a client, log in, and retrieve thread information.

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

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

### user_followers_gql

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

Get user’s followers information by Public Graphql API.

```APIDOC
## user_followers_gql(user_id: str, amount: int = 0)

### Description
Get user’s followers information by Public Graphql API.

### Parameters
- **user_id** (str) - Required
- **amount** (int) - Optional - Default: 0

### Response
- **List[UserShort]** - List of followers
```

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

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

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

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

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

### Initialize and save session

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

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

```python
from instagrapi import Client

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

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

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

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

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

```

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

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

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

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

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

### Configure Proxy and Regional Settings

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

Set proxy, locale, and timezone settings to simulate different user locations. Ensure the timezone offset is provided in seconds.

```python
cl = Client()

# Los Angles user:
cl.set_proxy('http://los:angeles@proxy.address:8080')
cl.set_locale('en_US')
cl.set_timezone_offset(-7 * 60 * 60)  # Los Angeles UTC (GMT) -7 hours == -25200 seconds
cl.get_settings()
{
    ...
    'user_agent': 'Instagram 194.0.0.36.172 Android (26/8.0.0; 480dpi; 1080x1920; Xiaomi; MI 5s; capricorn; qcom; en_US; 301484483)',
    'country': 'US',
    'country_code': 1,
    'locale': 'en_US',
    'timezone_offset': -25200
}

# Moscow user:
cl.set_proxy('socks5://moscow:proxy@address:8080')
cl.set_locale('ru_RU')
cl.set_country_code(7)  # +7
cl.set_timezone_offset(3 * 3600)  # Moscow UTC+3
cl.get_settings()
{
    ...
    'user_agent': 'Instagram 194.0.0.36.172 Android (26/8.0.0; 480dpi; 1080x1920; Xiaomi; MI 5s; capricorn; qcom; ru_RU; 301484483)',
    'country': 'RU',
    'country_code': 7,
    'locale': 'ru_RU',
    'timezone_offset': 10800
}
```

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

### Client Initialization

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

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

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

### Description
Initializes the instagrapi client instance used to interact with Instagram.

### Parameters
- **settings** (dict) - Optional - A dictionary containing device settings, authorization data, and cookies.
- **proxy** (str) - Optional - Proxy string (e.g., "socks5://127.0.0.1:30235").
- **tls_verify** (Union[bool, str]) - Optional - TLS certificate verification setting.
```

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

### 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 Hashtag Reels

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

Retrieves reels/clips associated with a specific hashtag using the private API.

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

### Description
Return reels/clips for a hashtag via private API.

### Method
`hashtag_medias_reels_v1`

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

### Return
List[Media] - A list of media objects representing reels/clips for the hashtag.
```

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

### Get Track URI

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

Extract the direct download URI for a track from its information. This URI can then be used for downloading.

```python
>>> track_uri = cl.track_info_by_canonical_id(18159860503036324).uri
HttpUrl('https://scontent-cph2-1.xx.fbcdn.net/v/t39.12897-6/84846439_2484536748531420_3971102873273499648_n.m4a?_nc_cat=101&ccb=1-7&_nc_sid=02c1ff&_nc_ohc=N6k7lDt_6TAAX_yKEoV&_nc_ad=z-m&_nc_cid=0&_nc_ht=scontent-cph2-1.xx&oh=00_AT9Cly5G-kzGxRceunBi8NUl5eFLEqwlMEJbWnxykUTO0Q&oe=62DF3A6E', scheme='https', host='scontent-cph2-1.xx.fbcdn.net', tld='net', host_type='domain', port='443', path='/v/t39.12897-6/84846439_2484536748531420_3971102873273499648_n.m4a', query='_nc_cat=101&ccb=1-7&_nc_sid=02c1ff&_nc_ohc=N6k7lDt_6TAAX_yKEoV&_nc_ad=z-m&_nc_cid=0&_nc_ht=scontent-cph2-1.xx&oh=00_AT9Cly5G-kzGxRceunBi8NUl5eFLEqwlMEJbWnxykUTO0Q&oe=62DF3A6E')
```

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

### Upload Media with Scheduling and Cross-posting

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

Demonstrates uploading photos and reels with scheduling, cross-posting to Facebook/Threads, and managing topics or custom metadata.

```python
>>> import time
>>> from pathlib import Path
>>> from instagrapi import Client

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

>>> scheduled_photo = cl.photo_upload(
...     "/app/image.jpg",
...     "Scheduled photo",
...     schedule_at=int(time.time()) + 3600,
... )

>>> crossposted_photo = cl.photo_upload(
...     "/app/image.jpg",
...     "Cross-posting this photo",
...     share_to_facebook=True,
...     share_to_threads=True,
... )

>>> crossposted_photo = cl.photo_upload(
...     "/app/image.jpg",
...     "Cross-posting with explicit destinations",
...     share_to_facebook=True,
...     fb_destination_id="FACEBOOK_DESTINATION_ID",
...     fb_destination_type="PAGE",
...     share_to_threads=True,
...     threads_destination_id="THREADS_PROFILE_ID",
... )

>>> if cl.clip_trial_eligible():
...     trial_reel = cl.clip_upload(
...         "/app/reel.mp4",
...         "Trying a new Reel format",
...         trial=True,
...     )

>>> topics = cl.clip_interest_topics()
>>> technology_topic = next(topic for topic in topics if topic["name"] == "Technology")
>>> reel = cl.clip_upload(
...     "/app/reel.mp4",
...     "Reel with a topic",
...     topics=[technology_topic["fit_id"]],
... )

>>> reel = cl.clip_upload(
...     "/app/reel.mp4",
...     "Cross-posting this Reel to Facebook",
...     share_to_facebook=True,
... )

>>> reel = cl.clip_upload(
...     "/app/reel.mp4",
...     "Cross-posting with explicit Facebook destination",
...     share_to_facebook=True,
...     fb_destination_id="FACEBOOK_DESTINATION_ID",
...     fb_destination_type="USER",
... )

>>> fb_extra = cl.clip_share_to_fb_extra_data(
...     destination_id="FACEBOOK_DESTINATION_ID",
...     destination_type="USER",
... )
>>> reel = cl.clip_upload(
...     "/app/reel.mp4",
...     "Cross-posting with explicit Facebook destination",
...     extra_data=fb_extra,
... )

>>> reel = cl.clip_upload(
...     "/app/reel.mp4",
...     "Reel with an updated cover",
...     thumbnail=Path("/app/cover-a.jpg"),
... )
>>> cl.clip_change_cover(reel.pk, Path("/app/cover-b.jpg"))

>>> media = cl.photo_upload(
    "/app/image.jpg",
    "Test caption for photo with #hashtags and mention users such @example",
    extra_data={
        "custom_accessibility_caption": "alt text example",
        "like_and_view_counts_disabled": 1,
        "disable_comments": 1,
    }
)

>>> media.dict()
```

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

### Download video by URL

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

Demonstrates authenticating, retrieving a media PK from a URL, and downloading a video file to a specified directory.

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

>>> cl.media_pk_from_url("https://www.instagram.com/p/BqNQJleFoSJ/")
1913256444155036809

>>> video_url = cl.media_info(1913256444155036809).video_url
>>> cl.video_download_by_url(video_url, folder='/tmp')
PosixPath('/tmp/45588546_367538213983456_6830188946193737023_n.mp4')
```

```python
>>> # Skip re-downloading if the target file already exists
>>> cl.video_download_by_url(video_url, folder='/tmp', overwrite=False)
PosixPath('/tmp/45588546_367538213983456_6830188946193737023_n.mp4')
```

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

### Get Media Comments

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

Retrieve all comments associated with a specific media. The result is a list of comment objects.

```python
>>> comments = cl.media_comments(media_id)
>>> comments[0].dict()
```

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

### Get Note Text by Username

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

Retrieves the text content of a Note associated with a specific username from a list of Notes.

```APIDOC
## get_note_text_by_user(notes: List[Note], username: str)

### Description
Get note text by username from a list of notes.

### Method
get_note_text_by_user

### Parameters
#### Path Parameters
- **notes** (List[Note]) - Required - A list of Note objects to search within.
- **username** (str) - Required - The username to search for.

### Response
#### Success Response (Optional[str])
- **text**: The text content of the Note, or None if not found.

### Request Example
```python
notes = cl.get_notes()
text = cl.get_note_text_by_user(notes, "something")
print(text)
```

### Response Example
```json
"Hello from Instagrapi, everyone can see it!"
```
```

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

### Configure a Proxy in instagrapi

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

Demonstrates how to set a proxy for an instagrapi client to ensure consistent network identity. Ensure the proxy string includes valid credentials and the correct protocol.

```python
from instagrapi import Client

cl = Client()
before_ip = cl._send_public_request("https://api.ipify.org/")
cl.set_proxy("http://username:password@proxy.example.com:8080")
after_ip = cl._send_public_request("https://api.ipify.org/")

print(f"Before: {before_ip}")
print(f"After: {after_ip}")
```

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

### Get Following Hashtags

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

Retrieve a list of hashtags that the authenticated user is following. The list may be limited by Instagram.

```python
>>> cl.hashtag_following(amount=1)
[Hashtag(id='17841562401125985', name='python', media_count=12000000, profile_pic_url=None)]
```

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

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

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

### Upload Story with Interactive Elements

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

Demonstrates uploading a video story with mentions, links, hashtags, media references, and polls.

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

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

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)],
    polls=[
        StoryPoll(
            x=0.5, y=0.5, width=0.7, height=0.5, question="Question", options=["Option 1", "Option 2", "Option 3"]
        )
    ],
)

cl.media_share_to_story(media_pk, caption="Shared to story")
```

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

### Get Highlight PK from URL

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

Extracts the unique highlight primary key (PK) from a given Instagram highlight URL.

```APIDOC
## highlight_pk_from_url

### Description
Get highlight PK from URL.

### Method
`highlight_pk_from_url(url: str)`

### Parameters
#### Path Parameters
- **url** (str) - Required - The URL of the Instagram highlight.

### Return
- **str** - The highlight's primary key.
```

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

### Get Inbox Activity - Python

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

Retrieves raw payload for 'Active recently' and inbox activity. Use `mark_as_seen=True` to mark all as seen.

```python
>>> cl.news_inbox_v1()
{'story_mentions': {'mentions_count_string': '0 stories mention you.',
  'reels': [],
  'product_stories_count': '0 stories mention your product.',
  'product_stories_reels': []},
 'counts': {'likes': 0,
  'activity_feed_dot_badge': 0,
  'relationships': 0,
  'new_posts': 0,
  'comments': 0,
  'comment_likes': 0,
  'shopping_notification': 0,
  'fundraiser': 0,
  'usertags': 0,
  'campaign_notification': 0,
  'photos_of_you': 0,
  'story_mentions': 0,
  'requests': 0},
 'last_checked': 1625468461.1633658,
 'friend_request_stories': [],
 'new_stories': [{'story_type': 159,
  'type': 13,
  'args': {'rich_text': 'An unrecognized XiaoMi MI 5s just logged in near Moscow, Russia, RU',
   'destination': 'login_activity',
   'icon_url': 'https://i.instagram.com/static/images/activity/info-1.5.png/3385260677b8.png',
   'should_icon_apply_filter': True,
   'icon_should_apply_filter': True,
   'extra': {'lat': 55.7522, 'long': 37.6156},
   'actions': ['hide'],
   'timestamp': 1625475888.805998,
   'tuuid': '0ceff44c-dd70-11eb-8080-808080808080',
   'clicked': False},
  'counts': {},
  'pk': 'xjQlWRMfNO+f739i2qZ1zf8HJTo='}],
 'old_stories': [{'type': 3,
  'story_type': 101,
  'args': {'links': [{'start': 24,
     'end': 33,
     ...
}
```

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

### story_download(story_pk: int, filename: str = "", folder: Path = "")

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

Downloads story media by its primary key.

```APIDOC
## story_download(story_pk: int, filename: str = "", folder: Path = "")

### Description
Download story media by media_type.

### Parameters
- **story_pk** (int) - Required - The primary key of the story.
- **filename** (str) - Optional - Custom filename.
- **folder** (Path) - Optional - Target folder path.
```

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

### Reusable login helper function

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

Encapsulate session loading and login logic into a reusable function using pathlib for file handling.

```python
from instagrapi import Client
from pathlib import Path


def login_user():
    """Login with a saved session and refresh it only when required."""
    session_file = Path("session.json")
    cl = Client()
    if session_file.exists():
        cl.load_settings(session_file)

    cl.login(USERNAME, PASSWORD)
    cl.dump_settings(session_file)
    return cl
```

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

### location_medias_recent

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

Get the most recent posts associated with a specific location, identified by its primary key (pk). Allows specifying the amount of posts to retrieve.

```APIDOC
## location_medias_recent

### Description
Get the most recent posts associated with a specific location, identified by its primary key (pk). Allows specifying the amount of posts to retrieve.

### Method
location_medias_recent

### Parameters
#### Path Parameters
- **location_pk** (int) - Required - The primary key of the location.
- **amount** (int) - Optional - The number of recent posts to retrieve. Defaults to 24.

### Return
List[Media]
```
Tokens:
Raw