### Hello World Example

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/getting-started.md

A basic example demonstrating how to log in, fetch user information, and retrieve user media.

```python
import asyncio
from aiograpi import Client

async def main():
    client = Client()
    await client.login("YOUR_USERNAME", "YOUR_PASSWORD")
    user = await client.user_info_by_username("instagram")
    print(user.full_name, user.follower_count)
    medias = await client.user_medias(user.pk, amount=3)
    for m in medias:
        print(m.code, m.caption_text[:60])

asyncio.run(main())
```

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

### Example Usage

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/captcha.md

An example demonstrating how to set a custom captcha handler and use it during client login.

```APIDOC
## Example Usage

### Description
This example shows how to define a custom captcha handler and register it with the `Client` before logging in.

### Code
```python
from aiograpi import Client

def my_captcha_handler(details: dict) -> str:
    # details contains: site_key, page_url, challenge_type, raw_challenge_json
    # Forward to your favorite captcha solver and return the token
    return solve_recaptcha(
        site_key=details["site_key"],
        page_url=details["page_url"],
    )


cl = Client()
cl.set_captcha_handler(my_captcha_handler)
await cl.login(USERNAME, PASSWORD)
```
```

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

### Install aiograpi

Source: https://github.com/subzeroid/aiograpi/blob/main/README.md

Install the aiograpi library using pip.

```bash
pip install aiograpi
```

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

### Install aiograpi

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/getting-started.md

Install the aiograpi library using pip. Requires Python 3.10+.

```bash
python -m pip install aiograpi
```

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

### Get Highlight PK from URL

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/highlight.md

Retrieves the primary key (PK) of a highlight given its 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 highlight.
```

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

### Get Hashtag Info and Media

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/hashtag.md

Demonstrates how to fetch hashtag information and recent media posts. Ensure you have logged in to the client before executing these calls.

```python
>>> from aiograpi import Client

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

>>> hashtag = await cl.hashtag_info('downhill')
>>> hashtag.dict()
{'id': 17841563089103670,
 'name': 'downhill',
 'media_count': 5178255,
 'profile_pic_url': HttpUrl('https://instagram.fhel3-1.fna.fbcdn.net/v/t51.2885-15/e35/s150x150/184304495_294863488920457_8839934375675895594_n.jpg?tp=1&_nc_ht=instagram.fhel3-1.fna.fbcdn.net&_nc_cat=101&_nc_ohc=L3i9yzFUBR8AX_MAXgr&edm=ABZsPhsBAAAA&ccb=7-4&oh=21a944a197506a42658e8273d92740b7&oe=60C37E35&_nc_sid=4efc9f', scheme='https', host='instagram.fhel3-1.fna.fbcdn.net', tld='net', host_type='domain', path='/v/t51.2885-15/e35/s150x150/184304495_294863488920457_8839934375675895594_n.jpg', query='tp=1&_nc_ht=instagram.fhel3-1.fna.fbcdn.net&_nc_cat=101&_nc_ohc=L3i9yzFUBR8AX_MAXgr&edm=ABZsPhsBAAAA&ccb=7-4&oh=21a944a197506a42658e8273d92740b7&oe=60C37E35&_nc_sid=4efc9f')}

>>> medias = await cl.hashtag_medias_top('downhill', amount=2)
>>> medias[0].dict()
{'pk': 2574092718364154697,
 'id': '2574092718364154697_376712420',
 'code': 'CO5A7BxA9tJ',
 'taken_at': datetime.datetime(2021, 5, 15, 10, 49, 45, tzinfo=datetime.timezone.utc),
 'media_type': 1,
 'product_type': '',
 'thumbnail_url': HttpUrl('https://instagram.fhel3-1.fna.fbcdn.net/v/t51.2885-15/e35/s1080x1080/186430270_473573763896149_2030909827389015824_n.jpg?tp=1&_nc_ht=instagram.fhel3-1.fna.fbcdn.net&_nc_cat=101&_nc_ohc=4jFHY_INCnMAX-7fObK&edm=AP_V10EBAAAA&ccb=7-4&oh=9fb0c4cdb01a7aa376a96c0df366d844&oe=60C4C01A&_nc_sid=4f375e', scheme='https', host='instagram.fhel3-1.fna.fbcdn.net', tld='net', host_type='domain', path='/v/t51.2885-15/e35/s1080x1080/186430270_473573763896149_2030909827389015824_n.jpg', query='tp=1&_nc_ht=instagram.fhel3-1.fna.fbcdn.net&_nc_cat=101&_nc_ohc=4jFHY_INCnMAX-7fObK&edm=AP_V10EBAAAA&ccb=7-4&oh=9fb0c4cdb01a7aa376a96c0df366d844&oe=60C4C01A&_nc_sid=4f375e'),
 'location': {'pk': 517543,
  'name': 'Sestola',
  'address': '',
  'lng': 10.77328,
  'lat': 44.2266,
  'external_id': 103150459725396,
  'external_id_source': 'facebook_places'},
 'user': {'pk': 376712420,
  'username': 'vascobica',
  'full_name': '⚡Vasco Bica®⚡',
  'profile_pic_url': HttpUrl('https://scontent-hel3-1.cdninstagram.com/v/t51.2885-19/s150x150/96211403_922669918147090_5138958292701151232_n.jpg?tp=1&_nc_ht=scontent-hel3-1.cdninstagram.com&_nc_ohc=tYlGX8kDuSgAX9WtBRF&edm=AP_V10EBAAAA&ccb=7-4&oh=ac96c75846d17519e53923a0ddb3aad0&oe=60C51486&_nc_sid=4f375e', scheme='https', host='scontent-hel3-1.cdninstagram.com', tld='com', host_type='domain', path='/v/t51.2885-19/s150x150/96211403_922669918147090_5138958292701151232_n.jpg', query='tp=1&_nc_ht=scontent-hel3-1.cdninstagram.com&_nc_ohc=tYlGX8kDuSgAX9WtBRF&edm=AP_V10EBAAAA&ccb=7-4&oh=ac96c75846d17519e53923a0ddb3aad0&oe=60C51486&_nc_sid=4f375e'),
  'stories': []},
 'comment_count': 8,
 'like_count': 327,
 'has_liked': None,
 'caption_text': 'Ready to fight ⚔️\n#js7 \n.\n.\n#swissmountainsports #racing #coppaitaliadh \n#mirandabikeparts\xa0#burning\xa0#jumping \xa0#whipit\xa0#scrubit\xa0#enduro\xa0#mtblife\xa0 #downhill\xa0#mountainbiking\xa0#sliding\xa0#dirt\xa0#dh\xa0 #mtb\xa0#bike\xa0#bikelife\xa0#friends\xa0#mtbswitzerland\xa0#downhillmtb\xa0#valais\xa0 #swissmountains\xa0\xa0#italy #italydownhill',
 'usertags': [{'user': {'pk': 3636959873,
    'username': 'christopherstrm',
    'full_name': 'Christopher Ström',
    'profile_pic_url': HttpUrl('https://scontent-hel3-1.cdninstagram.com/v/t51.2885-19/s150x150/173775865_527371595096868_8991176723035066304_n.jpg?tp=1&_nc_ht=scontent-hel3-1.cdninstagram.com&_nc_ohc=tbsAzTDoLtEAX_HaT9Z&edm=AP_V10EBAAAA&ccb=7-4&oh=94a18b3b4d0d39d9dbda849b4c23a5a9&oe=60C5192F&_nc_sid=4f375e', scheme='https', host='scontent-hel3-1.cdninstagram.com', tld='com', host_type='domain', path='/v/t51.2885-19/s150x150/173775865_527371595096868_8991176723035066304_n.jpg', query='tp=1&_nc_ht=scontent-hel3-1.cdninstagram.com&_nc_ohc=tbsAzTDoLtEAX_HaT9Z&edm=AP_V10EBAAAA&ccb=7-4&oh=94a18b3b4d0d39d9dbda849b4c23a5a9&oe=60C5192F&_nc_sid=4f375e'),
    'stories': []},
   'x': 0.211352657,
   'y': 0.8478260870000001}],
 'video_url': None,
 'view_count': 0,
 'video_duration': 0.0,
 'title': '',
 'resources': []}
```

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

### Get Media Information

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Fetch detailed information about a specific media item using its primary key (PK). The result is returned as a dictionary.

```python
>>> (await cl.media_info(1787135824035452364)).dict()
{'pk': 1787135824035452364,
 'id': '1787135824035452364_1903424587',
 'code': 'BjNLpA1AhXM',
 'taken_at': datetime.datetime(2018, 5, 25, 15, 46, 53, tzinfo=datetime.timezone.utc),
 'media_type': 8,
 'product_type': '',
 'thumbnail_url': None,
 'location': {'pk': 260916528,
  'name': 'Foros, Crimea',
  'address': '',
  'lng': 33.7878,
  'lat': 44.3914,
  'external_id': 181364832764479,
  'external_id_source': 'facebook_places'},
 'user': {'pk': 1903424587,
  'username': 'example',
  'full_name': 'Example Example',
  'profile_pic_url': HttpUrl('https://scontent-hel3-1.cdninstagram.com/v/t51.2885-19/s150x150/123884060_...&oe=5FD7600E')},
 'comment_count': 0,
 'like_count': 48,
 'caption_text': '@mind__flowers в Форосе под дождём, 24 мая 2018 #downhill #skateboarding #downhillskateboarding #crimea #foros',
 'usertags': [],
 'video_url': None,
 'view_count': 0,
 'video_duration': 0.0,
 'title': '',
 'resources': [{'pk': 1787135361353462176,
   'video_url': HttpUrl('https://scontent-hel3-1.cdninstagram.com/v/t50.2886-16/33464086_3755...0e2362', scheme='https', ...),
   'thumbnail_url': HttpUrl('https://scontent-hel3-1.cdninstagram.com/v/t51.2885-15/e35/3220311...AE7332', scheme='https', ...),
   'media_type': 2},
  {'pk': 1787135762219834098,
   'video_url': HttpUrl('https://scontent-hel3-1.cdninstagram.com/v/t50.2886-16/32895...61320_n.mp4', scheme='https', ...),
   'thumbnail_url': HttpUrl('https://scontent-hel3-1.cdninstagram.com/v/t51.2885-15/e35/3373413....8480_n.jpg', scheme='https', ...),
   'media_type': 2},
  {'pk': 1787133803186894424,
   'video_url': None,
   'thumbnail_url': HttpUrl('https://scontent-hel3-1.cdninstagram.com/v/t51.2885-15/e35/324307712_n.jpg...', scheme='https', ...),
   'media_type': 1}]}
```

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

### Get Highlight by PK or ID

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/highlight.md

Fetches highlight information using its primary key or ID.

```APIDOC
## highlight_info

### Description
Get Highlight by pk or id

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

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

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

### Get Media Information

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Fetch detailed information about a specific media item using its primary key.

```APIDOC
## media_info

### Description
Fetches detailed information about a media item using its primary key.

### Method Signature
`await cl.media_info(media_pk: int) -> MediaInfo`

### Parameters
* **media_pk** (int) - Required - The primary key of the media item.

### Request Example
```python
await cl.media_info(1787135824035452364)
```

### Response
* **MediaInfo**: An object containing detailed information about the media.
```

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

### Get Media Primary Key from URL

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

Retrieve the primary key (pk) of a media item using its full URL.

```APIDOC
## media_pk_from_url

### Description
Retrieves the primary key (pk) of a media item given its full URL.

### Method Signature
`await cl.media_pk_from_url(url: str) -> int`

### Parameters
* **url** (str) - Required - The full URL of the media item.

### Request Example
```python
await cl.media_pk_from_url("https://www.instagram.com/p/BjNLpA1AhXM/")
```

### Response
* **int**: The primary key of the media item.
```

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

### Get Direct Thread by Participants

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/direct.md

Retrieves a direct message thread based on a list of participant user IDs. This is useful for finding or starting a conversation with specific users.

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

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

### Basic Client Login and User Media Fetch

Source: https://github.com/subzeroid/aiograpi/blob/main/README.md

Initialize the Client, log in with credentials, and fetch a user's recent media. Ensure ACCOUNT_USERNAME and ACCOUNT_PASSWORD are set.

```python
from aiograpi import Client

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

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

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

### Initialize and Log in to aiograpi Client

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/interactions.md

Demonstrates how to initialize the aiograpi client with optional settings and log in using username and password. Includes commented examples for 2FA login and session ID login. Also shows how to set proxy configurations.

```python
await cl.login("aiograpi", "42")
# await cl.login("aiograpi", "42", verification_code="123456")  # with 2FA verification_code
# await 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(await cl.user_info(cl.user_id))
```

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

### Client Initialization and Login

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/interactions.md

Demonstrates how to initialize the aiograpi client and log in using different methods, including with and without 2FA, and by session ID. It also shows how to set proxies and retrieve client settings.

```APIDOC
## Client Initialization and Login

### Description
Initialize the `aiograpi` client and log in to your Instagram account.

### Methods
* `Client(settings: dict = {}, proxy: str = "")`: Initializes the `aiograpi` client.
* `login(username: str, password: str)`: Logs in by username and password.
* `login(username: str, password: str, verification_code: str)`: Logs in with 2FA verification code.
* `login_by_sessionid(sessionid: str)`: Logs in using a session ID.
* `set_proxy(proxy: str)`: Sets the proxy for the client.
* `get_settings()`: Retrieves the current client settings.
* `user_info(user_id: int)`: Retrieves information about a user.

### Request Example
```python
# Initialize client with default settings
cl = Client()

# Login with username and password
await cl.login("your_username", "your_password")

# Login with 2FA
# await cl.login("your_username", "your_password", verification_code="123456")

# Login by session ID
# cl.login_by_sessionid("your_session_id")

# Set a proxy
# cl.set_proxy("socks5://127.0.0.1:30235")

# Get client settings
print(cl.get_settings())

# Get user info
# print(await cl.user_info(cl.user_id))
```

### Settings Object Example
```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"
   },
   "cookies":  {},
   "last_login": 1596069420.0000145,
   "device_settings": {
      "cpu": "h1",
      "dpi": "640dpi",
      "model": "h1",
      "device": "RS988",
      "resolution": "1440x2392",
      "app_version": "117.0.0.28.123",
      "manufacturer": "LGE/lge",
      "version_code": "168361634",
      "android_release": "6.0.1",
      "android_version": 23
   },
   "user_agent": "Instagram 117.0.0.28.123 Android (23/6.0.1; ...US; 168361634)"
}

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

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

### Login and Fetch Direct Threads

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/direct.md

Demonstrates how to log in with provided credentials and fetch the first direct message thread. Ensure you have imported the Client class and have your USERNAME and PASSWORD defined.

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

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

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

### explore_page()

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/explore.md

Get the explore page payload.

```APIDOC
## explore_page()

### Description
Get the explore page payload.

### Method
`explore_page()`

### Return
dict
```

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

### Login and Fetch User Info

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/private-graphql.md

Demonstrates how to log in with username and password, then fetch user information using the `user_info_by_username_v2_gql` method. This method is preferred over older endpoints when logged in.

```python
from aiograpi import Client

cl = Client()
await cl.login(USERNAME, PASSWORD, verification_code="123456")

# v2 GraphQL profile fetch — preferred over user_info_by_username_gql
# when you're logged in (the legacy api/v1/users/web_profile_info/
# endpoint is increasingly flaky for authenticated callers).
user = await cl.user_info_by_username_v2_gql("instagram")
print(user.username, user.pk, user.follower_count)
```

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

### Get Specific Media Insights by URL - aiograpi

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/insight.md

Retrieve insights for a specific media post using its URL. This involves first getting the media's primary key (pk) from the URL and then fetching its insights. Requires login.

```python
from aiograpi import Client

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

media_pk = await cl.media_pk_from_url('https://www.instagram.com/p/CP5h-I1FuPr/')
await cl.insights_media(media_pk)
```

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

### Fetch User Reels

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/media.md

This example demonstrates how to fetch a user's reels using `user_clips_v1`. It shows how to access reel details like primary key, code, thumbnail URL, and location.

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

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

### Get Account Insights

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/insight.md

Retrieves statistics for your account.

```APIDOC
## insights_account

### Description
Get statistics by your account.

### Return
Dict - A dictionary containing account statistics.
```

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

### hashtag_medias_v1

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/hashtag.md

Get medias for a hashtag by Private Mobile API.

```APIDOC
## hashtag_medias_v1(name: str, amount: int = 27, tab_key: str = "top|recent")

### Description
Get medias for a hashtag by Private Mobile API.

### Parameters
#### Path Parameters
- **name** (str) - Required - The name of the hashtag.
- **amount** (int) - Optional - The amount of media to retrieve. Defaults to 27.
- **tab_key** (str) - Optional - The key for the tab to retrieve media from. Defaults to "top|recent".
```

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

### hashtag_medias_a1

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/hashtag.md

Get medias for a hashtag by Public Web API.

```APIDOC
## hashtag_medias_a1(name: str, amount: int = 27, tab_key: str = "edge_hashtag_to_top_posts|edge_hashtag_to_media")

### Description
Get medias for a hashtag by Public Web API.

### Parameters
#### Path Parameters
- **name** (str) - Required - The name of the hashtag.
- **amount** (int) - Optional - The amount of media to retrieve. Defaults to 27.
- **tab_key** (str) - Optional - The key for the tab to retrieve media from. Defaults to "edge_hashtag_to_top_posts|edge_hashtag_to_media".
```

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

### Set Up Proxy with aiograpi

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

Configure the aiograpi client to use a proxy service. This example demonstrates setting a SOAX proxy and verifying the IP address before and after the proxy is applied.

```python
from aiograpi import Client

cl = Client()
before_ip = await cl._send_public_request("https://api.ipify.org/")
cl.set_proxy("http://<api_key>:wifi;ca;;;toronto@proxy.soax.com:9137")
after_ip = await cl._send_public_request("https://api.ipify.org/")

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

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

### Initialize aiograpi Client with Custom Settings

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/interactions.md

Shows how to initialize the aiograpi client with pre-defined settings, including UUIDs, cookies, device settings, and user agent. This is useful for maintaining session state or using specific device configurations.

```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"
   },
   "cookies":  {},
   "last_login": 1596069420.0000145,
   "device_settings": {
      "cpu": "h1",
      "dpi": "640dpi",
      "model": "h1",
      "device": "RS988",
      "resolution": "1440x2392",
      "app_version": "117.0.0.28.123",
      "manufacturer": "LGE/lge",
      "version_code": "168361634",
      "android_release": "6.0.1",
      "android_version": 23
   },
   "user_agent": "Instagram 117.0.0.28.123 Android (23/6.0.1; ...US; 168361634)"
}

cl = Client(settings)
```

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

### hashtag_info_v1

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/hashtag.md

Get information about a hashtag by Private Mobile API.

```APIDOC
## hashtag_info_v1(name: str)

### Description
Get information about a hashtag by Private Mobile API.

### Parameters
#### Path Parameters
- **name** (str) - Required - The name of the hashtag.
```

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

### Client Initialization Change

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/migration.md

The `settings` dictionary passed to the Client is now deepcopied. Code relying on the reference identity of the original dictionary will need to be updated to use `client.settings` directly.

```python
Client(settings={"some": "dict"})  # caller-supplied dict was held by reference
```

```python
Client(settings={"some": "dict"})  # deepcopy'd, mutating it later won't leak in
```

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

### hashtag_info_gql

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/hashtag.md

Get information about a hashtag by Public Graphql API.

```APIDOC
## hashtag_info_gql(name: str, amount: int = 12, end_cursor: str = None)

### Description
Get information about a hashtag by Public Graphql API.

### Parameters
#### Path Parameters
- **name** (str) - Required - The name of the hashtag.
- **amount** (int) - Optional - The amount of information to retrieve. Defaults to 12.
- **end_cursor** (str) - Optional - The cursor for pagination.
```

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

### Get Notes

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/notes.md

Retrieve direct Notes from your Instagram account.

```APIDOC
## get_notes()

### Description
Retrieve direct Notes from your Instagram account.

### Method
GET (simulated)

### Endpoint
/api/v1/direct_ শেয়ার/notes/

### Parameters
None

### Response
#### Success Response (200)
- **List[Note]**: A list of Note objects.

### Response Example
```json
[
  {
    "id": "17849203563031468",
    "text": "Hello from Instagrapi, everyone can see it!",
    "user_id": 12312312312,
    "user": { ... },
    "audience": 0,
    "created_at": "2023-08-13T14:33:43Z",
    "expires_at": "2023-08-14T14:33:43Z",
    "is_emoji_only": false,
    "has_translation": false,
    "note_style": 0
  }
]
```
```

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

### hashtag_medias_recent_v1

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/hashtag.md

Get recent medias for a hashtag by Private Mobile API.

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

### Description
Get recent medias for a hashtag by Private Mobile API.

### Parameters
#### Path Parameters
- **name** (str) - Required - The name of the hashtag.
- **amount** (int) - Optional - The amount of recent media to retrieve. Defaults to 27.
```

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

### New Client Constructor Options

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/migration.md

The `Client` constructor now accepts a `logger` argument to pass a custom `logging.Logger` instance. This avoids the need for subclassing for custom logging.

```python
Client(logger=...)
```

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

### Login with Username and Password

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/troubleshooting.md

Log in to the client using your username and password before accessing private methods. Ensure this is done first.

```python
client = Client()
await client.login(USERNAME, PASSWORD)   # do this first
user = await client.user_info_v1("25025320")
```

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

### hashtag_medias_recent_a1

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/hashtag.md

Get recent medias for a hashtag by Public Web API.

```APIDOC
## hashtag_medias_recent_a1(name: str, amount: int = 71)

### Description
Get recent medias for a hashtag by Public Web API.

### Parameters
#### Path Parameters
- **name** (str) - Required - The name of the hashtag.
- **amount** (int) - Optional - The amount of recent media to retrieve. Defaults to 71.
```

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

### hashtag_medias_top_v1

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/hashtag.md

Get top medias for a hashtag by Private Mobile API.

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

### Description
Get top medias for a hashtag by Private Mobile API.

### Parameters
#### Path Parameters
- **name** (str) - Required - The name of the hashtag.
- **amount** (int) - Optional - The amount of top media to retrieve. Defaults to 9.
```

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

### Verifying Migration with Compilation and Typing

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/migration.md

Use these commands to catch syntax errors and type-checking issues after updating. Ensure your code is compatible with aiograpi's type hints.

```bash
python -m compileall your_code/      # catches syntax errors
```

```bash
mypy your_code/                      # picks up aiograpi's PEP 561
                                     # types (added in 0.4.0)
```

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

### hashtag_medias_top_a1

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/hashtag.md

Get top medias for a hashtag by Public Web API.

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

### Description
Get top medias for a hashtag by Public Web API.

### Parameters
#### Path Parameters
- **name** (str) - Required - The name of the hashtag.
- **amount** (int) - Optional - The amount of top media to retrieve. Defaults to 9.
```

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

### Configure Device Identity with Proxy and Locale

Source: https://context7.com/subzeroid/aiograpi/llms.txt

Set proxy, locale, country, and timezone to match the client's fingerprint with the proxy's geographic region. This helps reduce challenge rates. Persist these settings using dump_settings().

```python
from aiograpi import Client

cl = Client()

# Match a Los Angeles residential proxy
cl.set_proxy("http://user:pass@la-proxy.example.com:8080")
cl.set_locale("en_US")
cl.set_country("US")
cl.set_country_code(1)
cl.set_timezone_offset(-7 * 3600)  # UTC-7

print(cl.get_settings())
# {
#   'user_agent': 'Instagram 194.0.0.36.172 Android (26/8.0.0; 480dpi; ...; en_US; ...)',
#   'country': 'US', 'country_code': 1,
#   'locale': 'en_US', 'timezone_offset': -25200, ...
# }

# Persist the full device + session settings
cl.dump_settings("la_session.json")
```

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

### Update Synchronous Media-PK Helper Calls

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/migration.md

Media-PK helper functions that are now synchronous should be called directly without `await`. Using `await` will result in a `TypeError`.

```python
# Before
pk    = await client.media_pk_from_code(code)
code  = await client.media_code_from_pk(pk)
short = await client.media_pk(media_id)

# After
pk    = client.media_pk_from_code(code)
code  = client.media_code_from_pk(pk)
short = client.media_pk(media_id)  # staticmethod
```

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

### hashtag_medias_a1_chunk

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/hashtag.md

Get chunk of medias and end_cursor by Public Web API.

```APIDOC
## hashtag_medias_a1_chunk(name: str, max_amount: int = 27, tab_key: str = "edge_hashtag_to_top_posts|edge_hashtag_to_media", end_cursor: str = None)

### Description
Get chunk of medias and end_cursor by Public Web API.

### Parameters
#### Path Parameters
- **name** (str) - Required - The name of the hashtag.
- **max_amount** (int) - Optional - The maximum amount of media to retrieve. Defaults to 27.
- **tab_key** (str) - Optional - The key for the tab to retrieve media from. Defaults to "edge_hashtag_to_top_posts|edge_hashtag_to_media".
- **end_cursor** (str) - Optional - The cursor for pagination.
```

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

### Device and Proxy Management

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/interactions.md

Configure device settings and proxy servers for your client.

```APIDOC
## set_proxy(dsn: str)

### Description
Set the proxy server for requests. Supports socks and http/https proxy "scheme://username:password@host:port".

### Method
set_proxy

### Parameters
#### Request Body
- dsn (str) - Required - The Data Source Name for the proxy.

### Response
#### Success Response (dict)
- proxy_info (dict) - Information about the set proxy.

### Request Example
```python
proxy_info = cl.set_proxy('http://username:password@proxy.example.com:8080')
```
```

```APIDOC
## private.proxy

### Description
Stores used proxy server for private (mobile, v1) requests.

### Method
private.proxy

### Parameters
None

### Response
#### Success Response (dict)
- proxy_details (dict) - Details of the private proxy.

### Request Example
```python
private_proxy = cl.private.proxy
```
```

```APIDOC
## public.proxy

### Description
Stores used proxy server for public (web, graphql) requests.

### Method
public.proxy

### Parameters
None

### Response
#### Success Response (dict)
- proxy_details (dict) - Details of the public proxy.

### Request Example
```python
public_proxy = cl.public.proxy
```
```

```APIDOC
## set_device(device: dict)

### Description
Change device settings. Provide a dictionary with device information.

### Method
set_device

### Parameters
#### Request Body
- device (dict) - Required - Dictionary containing device information.

### Response
#### Success Response (bool)
- success (bool) - True if device settings were updated successfully, False otherwise.

### Request Example
```python
success = cl.set_device({'model': 'MI 5s', 'os': '8.0.0'})
```
```

```APIDOC
## device

### Description
Return the current device dictionary used for requests.

### Method
device

### Parameters
None

### Response
#### Success Response (dict)
- device_info (dict) - The current device configuration.

### Request Example
```python
current_device = cl.device
```
```

```APIDOC
## set_user_agent(user_agent: str = "")

### Description
Change the User-Agent header for requests.

### Method
set_user_agent

### Parameters
#### Request Body
- user_agent (str) - Optional - The User-Agent string to set. Defaults to an empty string.

### Response
#### Success Response (bool)
- success (bool) - True if the User-Agent was set successfully, False otherwise.

### Request Example
```python
success = cl.set_user_agent('Instagram 194.0.0.36.172 Android')
```
```

```APIDOC
## cookie_dict

### Description
Return the dictionary of cookies.

### Method
cookie_dict

### Parameters
None

### Response
#### Success Response (dict)
- cookies (dict) - The current cookies.

### Request Example
```python
cookies = cl.cookie_dict
```
```

```APIDOC
## user_id

### Description
Return the user ID after a successful login.

### Method
user_id

### Parameters
None

### Response
#### Success Response (int)
- user_id (int) - The logged-in user's ID.

### Request Example
```python
user_identifier = cl.user_id
```
```

```APIDOC
## base_headers

### Description
Return the base headers used for Instagram requests.

### Method
base_headers

### Parameters
None

### Response
#### Success Response (dict)
- headers (dict) - The base headers.

### Request Example
```python
headers = cl.base_headers
```
```

```APIDOC
## set_country(country: str = "US")

### Description
Set the country for the client. Recommended to match the proxy's country.

### Method
set_country

### Parameters
#### Request Body
- country (str) - Optional - The country code (e.g., "US"). Defaults to "US".

### Response
#### Success Response (bool)
- success (bool) - True if the country was set successfully, False otherwise.

### Request Example
```python
success = cl.set_country('US')
```
```

```APIDOC
## set_country_code(country_code: int = 1)

### Description
Set the country calling code. Default is 1 (USA).

### Method
set_country_code

### Parameters
#### Request Body
- country_code (int) - Optional - The country calling code (e.g., 1 for USA, 7 for Russia). Defaults to 1.

### Response
#### Success Response (bool)
- success (bool) - True if the country code was set successfully, False otherwise.

### Request Example
```python
success = cl.set_country_code(7)
```
```

```APIDOC
## set_locale(locale: str = "en_US")

### Description
Set the locale for the client. Recommended to match the proxy's locale.

### Method
set_locale

### Parameters
#### Request Body
- locale (str) - Optional - The locale string (e.g., "en_US", "ru_RU"). Defaults to "en_US".

### Response
#### Success Response (bool)
- success (bool) - True if the locale was set successfully, False otherwise.

### Request Example
```python
success = cl.set_locale('ru_RU')
```
```

```APIDOC
## set_timezone_offset(seconds: int)

### Description
Set the timezone offset in seconds from UTC.

### Method
set_timezone_offset

### Parameters
#### Request Body
- seconds (int) - Required - The timezone offset in seconds (e.g., -25200 for Los Angeles UTC-7).

### Response
#### Success Response (bool)
- success (bool) - True if the timezone offset was set successfully, False otherwise.

### Request Example
```python
success = cl.set_timezone_offset(-25200)
```
```

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

### explore_page_media_info(media_pk)

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/explore.md

Get media metadata for an explore page item.

```APIDOC
## explore_page_media_info(media_pk)

### Description
Get media metadata for an explore page item.

### Method
`explore_page_media_info(media_pk)`

### Parameters
#### Path Parameters
- **media_pk** (any) - Required - The primary key of the media item.

### Return
dict
```

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

### Get All Account Collections

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/collection.md

Retrieves a list of all collections associated with the account.

```APIDOC
## collections()

### Description
Get all account collections.

### Method
collections

### Return
List[Collection]
```

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

### Configure Proxy and Regional Settings (Los Angeles)

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/interactions.md

Set up proxy, locale, and timezone offset for a user in Los Angeles. This helps in mimicking a user from that specific region for more reliable interactions.

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

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

### Search Direct Threads

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/direct.md

Searches for direct message threads, for example, by username.

```APIDOC
## direct_search

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

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

### Parameters
- **query** (str) - Required - The search query string.
```

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

### Session Persistence with dump_settings and load_settings

Source: https://github.com/subzeroid/aiograpi/blob/main/README.md

Log in and save session settings to a file to avoid repeated logins. Load settings later to reuse the session. Ensure USERNAME and PASSWORD are set.

```python
from aiograpi import Client

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

# reload later without entering credentials again
cl = Client()
cl.load_settings("session.json")
await cl.login(USERNAME, PASSWORD)
```

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

### Get Direct Messages

Source: https://github.com/subzeroid/aiograpi/blob/main/docs/usage-guide/direct.md

Retrieves a list of direct messages from a specific thread.

```APIDOC
## Get Direct Messages

### Description
Retrieves a list of direct messages from a specific thread.

### Method
`GET`

### Endpoint
`/direct/threads/{thread_id}/messages`

### Parameters
#### Path Parameters
- **thread_id** (string) - Required - The unique identifier of the thread.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of messages to retrieve.

### Response
#### Success Response (200)
- **DirectMessage** (array) - A list of DirectMessage objects.
  - **id** (string) - The unique identifier of 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 timestamp when the message was sent.
  - **item_type** (string) - The type of the message content (e.g., 'text').
  - **text** (string) - The text content of the message.

#### Response Example
```json
[
  {
    "id": "300712312341231237412312312360",
    "user_id": "12312312",
    "thread_id": null,
    "timestamp": "2021-08-31T18:20:28.075413Z",
    "item_type": "text",
    "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua"
  }
]
```
```

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

### Saved Collections Management

Source: https://context7.com/subzeroid/aiograpi/llms.txt

Illustrates how to list all saved collections, get a collection's primary key by name, retrieve media within a collection, and save/unsave media. Requires client login.

```python
from aiograpi import Client

cl = Client()
await cl.login("my_username", "my_password")

# All collections
all_cols = await cl.collections()
for c in all_cols:
    print(c.pk, c.name)

# Get collection pk by name
col_pk = await cl.collection_pk_by_name("Favorites")

# Medias in a collection
medias = await cl.collection_medias(col_pk, amount=21)
for m in medias:
    print(m.code)

# Save / unsave media
media_pk = await cl.media_pk_from_url("https://www.instagram.com/p/CP5h-I1FuPr/")
media = await cl.media_info(media_pk)
await cl.media_save(media.id, collection_pk=col_pk)
await cl.media_unsave(media.id, collection_pk=col_pk)

# Liked media
liked = await cl.liked_medias(amount=21)
print([m.code for m in liked])
```