Skip to content

Upstream sync policy

aiograpi is the async port of instagrapi. Package versions remain independent, but every sync release records the instagrapi tag it has been ported through.

The current recorded upstream synchronization baseline is:

instagrapi 3.0.21

The applicable runtime changes through this baseline are included in aiograpi 2.0.17. This release requires TLS 1.3 for private curl requests, updates the default Android app profile to 449 while retaining saved 448 settings, clears stale account headers when authorization is reset, and includes the CAA context-pairing fix prepared for unpublished 2.0.16. Earlier ports shipped in 2.0.0–2.0.15 as shown below.

instagrapi release aiograpi release Ported behavior
3.0.0 2.0.0 CAA login and private curl_cffi HTTP/2 by default; explicit login_legacy() and saved transport choices remain supported.
3.0.1 2.0.1 Configured uploads return without a follow-up qe/expose/ request.
3.0.2 2.0.2 Current Reels response parsing, amount limits, cursor progress, and string media-ID stop markers.
3.0.3 2.0.3 Private GraphQL follow-list fallback and typed errors when Instagram explicitly requests CAA-to-legacy fallback.
3.0.4 2.0.4 FBNS authentication survives settings round trips; this fix originated in aiograpi.
3.0.5 2.0.5 Updated private GraphQL follower/following document IDs.
3.0.6–3.0.7 2.0.6 Current Reels configure payloads, story rich text, upload-status and video-resource helpers, and the default Android 448.0.0.0.20 profile.
3.0.8 2.0.7 Per-client caches and Highlights amount limits.
3.0.0 (omitted fallback from #2792) 2.0.8 Retry legacy needs_upgrade errors through CAA, forwarding the verification code and preserving the original error and diagnostics if CAA returns no session.
3.0.9 2.0.8 Separate HTTP helper timeouts from request pacing.
3.0.10 2.0.9 Normalize nullable media crosspost and coauthor fields; retain the existing typed CAA fallback errors.
3.0.11 2.0.10 Reuse the saved session for related profiles and update the shared web profile query, variables, and short-profile headers.
3.0.12 2.0.11 Require curl-adapter 1.2.3 for optional public curl response-body compatibility with urllib3 2.8.
3.0.13 2.0.12 Normalize carousel resource IDs in app profile timeline responses before extraction.
3.0.14 2.0.13 Restore the optional public curl media-info PostRoot query; the instagrapi login diagnostic helper change is sync-only.
3.0.15 2.0.14 Extract literal CAA profile-code contexts from nested static server parameters while preserving operand positions.
3.0.16 2.0.15 Normalize raw Highlight owners before validation, preserving relationship values and story order.
3.0.17 Not applicable The requests-response HTTP-status fix and per-attempt login diagnostic helper are sync-specific; native async responses already preserve HTTP status.
3.0.18 2.0.17 (prepared in unpublished 2.0.16) Pair CAA two-step contexts with their parameter keys, preserve scalar positions, and match exact quoted app references.
3.0.19 2.0.17 Clear stale account routing and claim headers on authorization reset while preserving device identity and valid-session reuse.
3.0.20 2.0.17 Use the native Android 449 profile, retain saved 448 settings, and preserve the existing CAA login payload.
3.0.21 2.0.17 Require TLS 1.3 for private curl requests while retaining hybrid/classical groups and HTTP/2. Standalone login diagnostics and development-tool changes are sync-specific.

See the login migration guide for the current defaults and compatibility options. From aiograpi 2.0.3, login() follows an explicit fallback instruction returned by Instagram; it does not retry every failed CAA login through the legacy endpoint.

The login_legacy() fix in 2.0.8 applies only to a needs_upgrade error, including differences in letter case or surrounding whitespace. Unrelated UnknownError responses still propagate directly, and typed CAA failures and async cancellation retain their existing behavior.

aiograpi 1.0.x established the SemVer async baseline through instagrapi 2.7.17, including Bloks login fallback updates, backup-code 2FA, email and phone helper work, password reset helpers, album per-slide usertags, comment pin/unpin endpoint fixes, username normalization, private GraphQL followers helpers, Story music upload helpers, scheduled feed uploads, professional account conversion helpers, coauthor upload helpers, and the private media-info lookup fix for video downloads.

aiograpi 1.1.0 continues the mirror through instagrapi 2.8.2. It adds experimental async Realtime MQTT/MQTToT, Direct message sync and lightweight Direct MQTT actions, async FBNS push MQTT with token registration and persisted device-auth state, phone confirmation-code support, followed hashtag helpers, feed-media share-to-story, opaque Bloks challenge context handling, and clearer Reel/clip upload failure details.

aiograpi 1.2.x continues the mirror through instagrapi 2.8.19. It adds Direct media share to existing threads, Direct message request privacy exceptions, private-first high-level user/media/story lookups for authenticated clients, sessionid username recovery via private profile stream, clear manual handling for Bloks redirect checkpoints, confirmed Reel Facebook destination normalization, hashtag private section fixes, private business contact field mapping, story metadata extraction, and private incomplete-read retry handling.

aiograpi 1.3.0 continues the mirror through instagrapi 2.9.0. It adds the experimental modern CAA email signup flow via signup_caa_email(...), the graphql_www Bloks app wrapper used by registration, and per-request private headers/domain routing so Bloks friendly names do not leak onto unrelated private requests.

aiograpi 1.3.1 continues the baseline through instagrapi 2.9.1 and adds the async user_suggested_profiles(...) convenience helper for composing chaining and expanded suggestion details.

aiograpi 1.4.15 continues the baseline through instagrapi 2.10.14 and adds async story poll voting via story_poll_vote(...) plus private Story.polls extraction for story poll sticker ids, questions, options, and vote state.

aiograpi 1.5.0 continues the baseline through instagrapi 2.11.0 and ports the user_follow(...) action-count/cache semantics fix so duplicate follow attempts return False when the relationship already exists or is pending.

aiograpi 1.6.0 continues the baseline through instagrapi 2.12.0 and ports typed preservation for v2-only UserShort fields in private GraphQL follow-list payloads, including friendship_status and normalized latest_reel_media.

aiograpi 1.12.14 continues the baseline through instagrapi 2.18.18. Its HTTPX transport already exposes the final HTTP response directly, so exhausted 429 responses map to ClientThrottledError or PleaseWaitFewMinutes without leaking urllib3 retry errors or adding a second transport retry layer.

The instagrapi 2.18.19 transport port introduced optional native async private HTTP/2 through curl_cffi in aiograpi 1.12.15, preserving HTTPX request preparation, redirects and cookies. The private transport API, saved settings, guarded CAA/saved-session live tests and real TLS/HTTP2 CI coverage were mirrored; default login routing remained unchanged in that release. aiograpi 1.12.16 recorded the 2.18.20 TLS group update. The aiograpi 2.0.0 defaults supersede those earlier opt-in instructions.

Release policy

  • Use one aiograpi feature release for a large upstream sync.
  • Keep patch releases for urgent fixes after that sync lands.
  • Mention the upstream range in GitHub, PyPI, and Telegram release notes.

For the 2026-05 sync, the public releases are aiograpi 0.9.0 and newer. aiograpi 0.9.0 synced through instagrapi 2.5.18, and subsequent aiograpi 0.9.x patch releases continued that baseline through instagrapi 2.6.8, plus targeted maintenance ports. aiograpi 1.0.x recorded the SemVer async baseline through instagrapi 2.7.17; aiograpi 1.1.0 records the MQTT/FBNS baseline through instagrapi 2.8.2; aiograpi 1.2.x records the follow-up high-level/private-first, Reel Facebook destination, hashtag, metadata, and private incomplete-read retry baseline through instagrapi 2.8.19; aiograpi 1.3.0 records the CAA signup baseline through instagrapi 2.9.0; aiograpi 1.3.1 records the suggested-profiles helper baseline through instagrapi 2.9.1; aiograpi 1.3.16 records the Reel mashup-info helper baseline through instagrapi 2.9.16; aiograpi 1.3.17 records the bookmarked music helper baseline through instagrapi 2.9.17; aiograpi 1.3.18 records the address book suggestions helper baseline through instagrapi 2.9.18; aiograpi 1.3.19 records the typed address book helper baseline through instagrapi 2.9.19; aiograpi 1.4.0 records the challenge api-path normalization baseline through instagrapi 2.10.0; aiograpi 1.4.1 records the canonical track not-found baseline through instagrapi 2.10.1; aiograpi 1.4.2 records the XDT sidecar media-info baseline through instagrapi 2.10.2; aiograpi 1.4.3 records the account-edit exception mapping baseline through instagrapi 2.10.3; aiograpi 1.4.4 records the UserShort.stories regression baseline through instagrapi 2.10.4; aiograpi 1.4.5 records the typed suggested-profiles helper baseline through instagrapi 2.10.5; aiograpi 1.4.6 records the collection cursor fallback regression baseline through instagrapi 2.10.6; aiograpi 1.4.7 records the Windows thumbnail-handle upload cleanup baseline through instagrapi 2.10.7; aiograpi 1.4.8 records the Bloks redirect challenge resume baseline through instagrapi 2.10.8; aiograpi 1.4.9 records the coauthor upload helper baseline through instagrapi 2.10.9; aiograpi 1.4.10 records the public comments helper baseline through instagrapi 2.10.10; aiograpi 1.4.11 records the public-first photo download baseline through instagrapi 2.10.11; aiograpi 1.4.12 keeps that baseline and fixes sessionless legacy signup requests in the async port; aiograpi 1.4.13 records the Clips seen-state helper baseline through instagrapi 2.10.12; aiograpi 1.4.14 records the Reel topics/upload auth baseline through instagrapi 2.10.13; aiograpi 1.4.15 records the story poll vote baseline through instagrapi 2.10.14; aiograpi 1.5.0 records the user-follow action-count/cache baseline through instagrapi 2.11.0; aiograpi 1.6.0 records the v2 UserShort field preservation baseline through instagrapi 2.12.0.

Porting rules

  • Preserve the async public API.
  • Convert instagrapi imports to aiograpi.
  • Await network-bound methods such as private_request, public_request, and public_graphql_request.
  • Keep pure helpers synchronous.
  • Add or port regression tests before behavior changes when practical.
  • Run Ruff, regression tests, docs build, and package build before tagging.

Automated release tracking

The Upstream Sync Tracker workflow checks GitHub's latest stable instagrapi release every day at 06:17 UTC. It compares that tag with __upstream_instagrapi_version__ and creates one durable sync issue when the upstream version is newer. Existing issues are matched by exact title across open and closed states, so a closed or superseded tracker is not recreated daily.

Maintainers can also run the workflow with an explicit tag through workflow_dispatch or send the existing repository_dispatch event with event_type instagrapi_release and client_payload.tag set to a stable three-component X.Y.Z tag, such as 2.18.19. All modes record:

  • previous instagrapi baseline;
  • new instagrapi tag;
  • compare URL;
  • checklist of changed files and release-note items.

GitHub schedules are best-effort. They run from the default branch, can be delayed or dropped during high Actions load, and are disabled for public repositories after 60 days without repository activity. Manual dispatch can replace delayed or dropped scheduled runs. If GitHub disables the workflow after 60 days of inactivity, maintainers must first re-enable it in Actions or with gh workflow enable upstream-sync.yml, then dispatch it.