Skip to content

Getting Started

Installation

python -m pip install aiograpi

Requires Python 3.10+.

Hello world

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

That's it. You're talking to Instagram's private API.

What you'll need beyond pip install

  • An Instagram account. A real one — IG flags fresh / unverified accounts within a few requests.
  • (Strongly recommended) A residential proxy. Datacenter IPs get rate-limited and challenge-walled fast. Pass it via client.set_proxy("http://user:pass@host:port").
  • (If 2FA is on) A TOTP code or seed. Pass verification_code= to login(), or pre-generate from a seed via client.totp_generate_code(seed).

If login() raises ChallengeRequired or BadPassword, that's Instagram pushing back — see the Challenge Resolver and Handle Exceptions guides.

Public, anonymous calls (no login)

For some endpoints you can skip login entirely:

client = Client()
user = await client.user_info_by_username_gql("instagram")
print(user.username, user.pk)  # → "instagram", "25025320"

Methods with the _gql suffix hit the public web GraphQL surface and work anonymously. Methods with _v1 need login.

What's Next?