{"openapi":"3.1.0","info":{"title":"Instoryview Open API","version":"1.0.0","description":"Six operations for stored Instagram account data, readable tracking snapshots and explicitly budgeted public queries. Lists may be partial. Instoryview is not affiliated with Instagram or Meta.","termsOfService":"https://instoryview.com/terms","contact":{"email":"support@instoryview.com","url":"https://instoryview.com/docs"}},"servers":[{"url":"https://instoryview.com/open-api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Stored reads"},{"name":"Online queries"}],"paths":{"/tracking":{"get":{"operationId":"list_tracking","summary":"List my tracked accounts","description":"Defaults to active and paused accounts. Counts and snapshot timestamps are included per account. No fresh provider calls.","tags":["Stored reads"],"x-required-scopes":["data:read"],"parameters":[{"name":"includeArchived","in":"query","description":"Include readable removed tracking records.","schema":{"type":"boolean","default":false}},{"name":"limit","in":"query","description":"Items per stored read page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"Opaque nextCursor from this same stored endpoint and authorization.","schema":{"type":"string"}}],"responses":{"200":{"description":"Stored data. No new collection charge.","headers":{"Cache-Control":{"schema":{"type":"string","const":"private, no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackingResponse"},"example":{"data":{"items":[{"id":"123456789","username":"sample_creator","fullName":"Sample Creator","avatarUrl":null,"status":"active","trackedLists":["followers"],"followerCount":1200,"followingCount":420,"profileAsOf":"2026-10-11T08:00:00Z","listSnapshots":{"followers":"2026-10-11T09:00:00Z","following":null}}]},"meta":{"requestId":"req_example","source":"tracking_history","asOf":null,"creditsUsed":0,"warnings":[],"coverage":"partial","hasMore":false,"nextCursor":null}}}}},"400":{"description":"validation_failed: invalid username, filters or cursor. from/to must be supplied together.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"validation_failed","message":"Check the request parameters."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"401":{"description":"unauthorized: credential missing, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"A valid API Key is required."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"403":{"description":"insufficient_scope, list_not_authorized or forbidden: current access does not authorize the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"list_not_authorized","message":"This credential cannot access the requested list."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"404":{"description":"snapshot_unavailable, data_unavailable or not_found. Missing data is not an empty list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"snapshot_unavailable","message":"No retained readable follower snapshot is available."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"409":{"description":"account_changed or data_changed: restart the stored read after checking account identity and access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"data_changed","message":"Restart the stored read after checking account identity and access."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"410":{"description":"cursor_expired: the stored paging context is no longer available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"cursor_expired","message":"This paging context expired. Start a new stored read."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"429":{"description":"rate_limited: wait before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"Wait before retrying."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"500":{"description":"internal: request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal","message":"The request could not be completed."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"503":{"description":"upstream_unavailable: temporarily unavailable. Recover paid operations with their original idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The source is temporarily unavailable."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}}}}},"/accounts/{username}":{"get":{"operationId":"get_account","summary":"Read existing account profile and totals","description":"Reads stored profile or permitted reusable public data. Unknown counts are null. Profile observation time may differ from list time.","tags":["Stored reads"],"x-required-scopes":["data:read"],"parameters":[{"name":"username","in":"path","required":true,"description":"Instagram username. Pagination remains bound to the resolved stable account ID.","schema":{"type":"string","pattern":"^@?[A-Za-z0-9_][A-Za-z0-9_.]{0,29}$"},"example":"sample_creator"}],"responses":{"200":{"description":"Stored data. No new collection charge.","headers":{"Cache-Control":{"schema":{"type":"string","const":"private, no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileResponse"},"example":{"data":{"id":"123456789","username":"sample_creator","fullName":"Sample Member","avatarUrl":null,"isPrivate":false,"isVerified":false,"followerCount":1200,"followingCount":420,"trackedLists":["followers","following"]},"meta":{"requestId":"req_profile_example","source":"stored_profile","asOf":"2026-10-11T08:00:00Z","creditsUsed":0,"warnings":[]}}}}},"400":{"description":"validation_failed: invalid username, filters or cursor. from/to must be supplied together.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"validation_failed","message":"Check the request parameters."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"401":{"description":"unauthorized: credential missing, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"A valid API Key is required."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"403":{"description":"insufficient_scope, list_not_authorized or forbidden: current access does not authorize the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"list_not_authorized","message":"This credential cannot access the requested list."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"404":{"description":"snapshot_unavailable, data_unavailable or not_found. Missing data is not an empty list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"snapshot_unavailable","message":"No retained readable follower snapshot is available."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"409":{"description":"account_changed or data_changed: restart the stored read after checking account identity and access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"data_changed","message":"Restart the stored read after checking account identity and access."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"410":{"description":"cursor_expired: the stored paging context is no longer available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"cursor_expired","message":"This paging context expired. Start a new stored read."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"429":{"description":"rate_limited: wait before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"Wait before retrying."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"500":{"description":"internal: request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal","message":"The request could not be completed."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"503":{"description":"upstream_unavailable: temporarily unavailable. Recover paid operations with their original idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The source is temporarily unavailable."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}}}}},"/accounts/{username}/followers":{"get":{"operationId":"list_followers","summary":"Read an available follower snapshot","description":"Selects the caller-readable last usable published follower snapshot. Paused or removed tracking reads only retained authorized-period data. Never-tracked accounts may read reusable public query data. No implicit fresh query.","tags":["Stored reads"],"x-required-scopes":["data:read"],"parameters":[{"name":"username","in":"path","required":true,"description":"Instagram username. Pagination remains bound to the resolved stable account ID.","schema":{"type":"string","pattern":"^@?[A-Za-z0-9_][A-Za-z0-9_.]{0,29}$"},"example":"sample_creator"},{"name":"limit","in":"query","description":"Items per stored read page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"Opaque nextCursor from this same stored endpoint and authorization.","schema":{"type":"string"}}],"responses":{"200":{"description":"Stored data. No new collection charge.","headers":{"Cache-Control":{"schema":{"type":"string","const":"private, no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListResponse"},"example":{"data":{"accountId":"123456789","username":"sample_creator","availableCount":850,"returnedCount":1,"items":[{"id":"234567890","username":"sample_member","fullName":"Sample Member","avatarUrl":null,"isPrivate":false,"isVerified":false}]},"meta":{"requestId":"req_example","source":"tracking_snapshot","asOf":"2026-10-11T09:00:00Z","creditsUsed":0,"warnings":["partial_list"],"coverage":"partial","hasMore":false,"nextCursor":null}}}}},"400":{"description":"validation_failed: invalid username, filters or cursor. from/to must be supplied together.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"validation_failed","message":"Check the request parameters."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"401":{"description":"unauthorized: credential missing, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"A valid API Key is required."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"403":{"description":"insufficient_scope, list_not_authorized or forbidden: current access does not authorize the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"list_not_authorized","message":"This credential cannot access the requested list."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"404":{"description":"snapshot_unavailable, data_unavailable or not_found. Missing data is not an empty list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"snapshot_unavailable","message":"No retained readable follower snapshot is available."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"409":{"description":"account_changed or data_changed: restart the stored read after checking account identity and access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"data_changed","message":"Restart the stored read after checking account identity and access."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"410":{"description":"cursor_expired: the stored paging context is no longer available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"cursor_expired","message":"This paging context expired. Start a new stored read."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"429":{"description":"rate_limited: wait before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"Wait before retrying."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"500":{"description":"internal: request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal","message":"The request could not be completed."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"503":{"description":"upstream_unavailable: temporarily unavailable. Recover paid operations with their original idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The source is temporarily unavailable."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}}}}},"/accounts/{username}/following":{"get":{"operationId":"list_following","summary":"Read an available following snapshot","description":"Same structure as followers; the following snapshot and entitlement are selected independently. Cursor must come from this endpoint and current caller.","tags":["Stored reads"],"x-required-scopes":["data:read"],"parameters":[{"name":"username","in":"path","required":true,"description":"Instagram username. Pagination remains bound to the resolved stable account ID.","schema":{"type":"string","pattern":"^@?[A-Za-z0-9_][A-Za-z0-9_.]{0,29}$"},"example":"sample_creator"},{"name":"limit","in":"query","description":"Items per stored read page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"Opaque nextCursor from this same stored endpoint and authorization.","schema":{"type":"string"}}],"responses":{"200":{"description":"Stored data. No new collection charge.","headers":{"Cache-Control":{"schema":{"type":"string","const":"private, no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListResponse"},"example":{"data":{"accountId":"123456789","username":"sample_creator","availableCount":850,"returnedCount":1,"items":[{"id":"234567890","username":"sample_member","fullName":"Sample Member","avatarUrl":null,"isPrivate":false,"isVerified":false}]},"meta":{"requestId":"req_following_example","source":"tracking_snapshot","asOf":"2026-10-11T09:00:00Z","creditsUsed":0,"warnings":["partial_list"],"coverage":"partial","hasMore":false,"nextCursor":null}}}}},"400":{"description":"validation_failed: invalid username, filters or cursor. from/to must be supplied together.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"validation_failed","message":"Check the request parameters."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"401":{"description":"unauthorized: credential missing, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"A valid API Key is required."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"403":{"description":"insufficient_scope, list_not_authorized or forbidden: current access does not authorize the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"list_not_authorized","message":"This credential cannot access the requested list."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"404":{"description":"snapshot_unavailable, data_unavailable or not_found. Missing data is not an empty list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"snapshot_unavailable","message":"No retained readable follower snapshot is available."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"409":{"description":"account_changed or data_changed: restart the stored read after checking account identity and access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"data_changed","message":"Restart the stored read after checking account identity and access."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"410":{"description":"cursor_expired: the stored paging context is no longer available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"cursor_expired","message":"This paging context expired. Start a new stored read."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"429":{"description":"rate_limited: wait before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"Wait before retrying."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"500":{"description":"internal: request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal","message":"The request could not be completed."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"503":{"description":"upstream_unavailable: temporarily unavailable. Recover paid operations with their original idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The source is temporarily unavailable."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}}}}},"/accounts/{username}/changes":{"get":{"operationId":"get_account_changes","summary":"Read detected tracking changes","description":"Reads only authorized confirmed changes. Summary covers the readable range; items is one page. Unknown values stay null. Detection time is not action time. Cursor fixes the observation context.","tags":["Stored reads"],"x-required-scopes":["data:read"],"parameters":[{"name":"username","in":"path","required":true,"description":"Instagram username. Pagination remains bound to the resolved stable account ID.","schema":{"type":"string","pattern":"^@?[A-Za-z0-9_][A-Za-z0-9_.]{0,29}$"},"example":"sample_creator"},{"name":"list","in":"query","schema":{"type":"string","enum":["followers","following"],"default":"followers"}},{"name":"from","in":"query","description":"Inclusive start date. Requires to. Defaults to the last seven calendar days; at most 366 days.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"Inclusive end date. Requires from.","schema":{"type":"string","format":"date"}},{"name":"timezone","in":"query","description":"IANA timezone that defines the date window.","schema":{"type":"string","default":"UTC"}},{"name":"limit","in":"query","description":"Items per stored read page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","description":"Opaque nextCursor from this same stored endpoint and authorization.","schema":{"type":"string"}}],"responses":{"200":{"description":"Stored data. No new collection charge.","headers":{"Cache-Control":{"schema":{"type":"string","const":"private, no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesResponse"},"example":{"data":{"accountId":"123456789","username":"sample_creator","list":"followers","from":"2026-10-01","to":"2026-10-07","timezone":"UTC","summary":{"added":12,"removed":3,"netDiscovered":9,"countNetChange":7},"items":[{"id":"event_example","kind":"new_follower","detectedAt":"2026-10-07T09:00:00Z","account":{"id":"234567890","username":"sample_member"}}]},"meta":{"requestId":"req_example","source":"tracking_history","asOf":"2026-10-07T09:00:00Z","creditsUsed":0,"warnings":["detected_changes_only"],"coverage":"partial","hasMore":false,"nextCursor":null}}}}},"400":{"description":"validation_failed: invalid username, filters or cursor. from/to must be supplied together.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"validation_failed","message":"Check the request parameters."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"401":{"description":"unauthorized: credential missing, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"A valid API Key is required."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"403":{"description":"insufficient_scope, list_not_authorized or forbidden: current access does not authorize the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"list_not_authorized","message":"This credential cannot access the requested list."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"404":{"description":"snapshot_unavailable, data_unavailable or not_found. Missing data is not an empty list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"snapshot_unavailable","message":"No retained readable follower snapshot is available."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"409":{"description":"account_changed or data_changed: restart the stored read after checking account identity and access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"data_changed","message":"Restart the stored read after checking account identity and access."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"410":{"description":"cursor_expired: the stored paging context is no longer available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"cursor_expired","message":"This paging context expired. Start a new stored read."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"429":{"description":"rate_limited: wait before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"Wait before retrying."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"500":{"description":"internal: request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal","message":"The request could not be completed."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"503":{"description":"upstream_unavailable: temporarily unavailable. Recover paid operations with their original idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The source is temporarily unavailable."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}}}}},"/queries":{"post":{"operationId":"query_public_account","summary":"Query fresh public account data within a budget","tags":["Online queries"],"description":"Explicitly queries a public profile or one list page (at most 25 people), including for an untracked account. Requires both scopes and a positive maxCredits. No implicit tracking or full export. Each online next page is a new logical operation with a new idempotency key and cap. All billable prerequisite calls count against the cap. Failures may have confirmed source costs. Recovery preserves the original key and body.","x-required-scopes":["data:read","data:fetch"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique key for one logical paid query. Preserve for recovery. Same key with a different body conflicts.","schema":{"type":"string","minLength":8,"maxLength":200,"pattern":"^[A-Za-z0-9_.:-]{8,200}$"},"example":"71973fa2-05dd-4e35-b0b5-e21b7f3d9558"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"},"examples":{"profile":{"value":{"username":"sample_creator","type":"profile","maxCredits":2}},"followers":{"value":{"username":"sample_creator","type":"followers","maxCredits":2}},"following":{"value":{"username":"sample_creator","type":"following","maxCredits":2}},"nextPage":{"value":{"username":"sample_creator","type":"followers","cursor":"ONLINE_CURSOR","maxCredits":2}}}}}},"responses":{"200":{"description":"Fresh profile or one list page. Idempotent replay returns the original total cost, without charging again.","headers":{"Cache-Control":{"schema":{"type":"string","const":"private, no-store"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProfileResponse"},{"$ref":"#/components/schemas/ListResponse"}]},"example":{"data":{"accountId":"123456789","username":"sample_creator","availableCount":null,"returnedCount":1,"items":[{"id":"234567890","username":"sample_member","fullName":"Sample Member","avatarUrl":null,"isPrivate":false,"isVerified":false}]},"meta":{"requestId":"req_example","source":"live","asOf":"2026-10-11T09:00:00Z","creditsUsed":2,"warnings":["partial_list"],"coverage":"partial","hasMore":false,"nextCursor":null}}}}},"400":{"description":"validation_failed: invalid username, filters or cursor. from/to must be supplied together.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"validation_failed","message":"Check the request parameters."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"401":{"description":"unauthorized: credential missing, expired or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"unauthorized","message":"A valid API Key is required."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"402":{"description":"budget_exceeded or insufficient_credits: request cannot fit its cap, shared daily cap or wallet balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"budget_exceeded","message":"The request cannot fit the available budget."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"403":{"description":"insufficient_scope, list_not_authorized or forbidden: current access does not authorize the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"list_not_authorized","message":"This credential cannot access the requested list."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"404":{"description":"snapshot_unavailable, data_unavailable or not_found. Missing data is not an empty list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"snapshot_unavailable","message":"No retained readable follower snapshot is available."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"409":{"description":"idempotency_conflict, request_in_progress, query_outcome_unknown, account_changed or data_changed. Retry in-progress with the original key, at most 60 seconds automatically. Stop automatic retries on unknown outcome; keep the original key for later manual recovery.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Present when the same operation is still in progress."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"request_in_progress","message":"Recover the same operation with its original key."},"meta":{"requestId":"req_error_example","creditsUsed":null}}}}},"410":{"description":"cursor_expired or result_expired. Expired results never authorize another collection with the old key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"result_expired","message":"The result expired; the old key will not collect again."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"429":{"description":"rate_limited: wait before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"rate_limited","message":"Wait before retrying."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"500":{"description":"internal: request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"internal","message":"The request could not be completed."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}},"503":{"description":"upstream_unavailable: temporarily unavailable. Recover paid operations with their original idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"upstream_unavailable","message":"The source is temporarily unavailable."},"meta":{"requestId":"req_error_example","creditsUsed":0}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Personal Instoryview API Key. OAuth tokens are bound to the MCP resource and are not accepted on these REST endpoints. data:read is required on every operation; online queries also require data:fetch."}},"schemas":{"Meta":{"type":"object","properties":{"requestId":{"type":"string"},"source":{"type":"string","enum":["stored_profile","tracking_snapshot","tracking_history","public_cache","live"]},"asOf":{"type":["string","null"],"format":"date-time"},"creditsUsed":{"type":"integer","minimum":0},"warnings":{"type":"array","items":{"type":"string"}},"coverage":{"type":"string","enum":["partial","unknown","complete"],"description":"complete requires authoritative evidence; page end alone is insufficient."},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["requestId","source","asOf","creditsUsed","warnings"],"additionalProperties":false},"PagedMeta":{"type":"object","properties":{"requestId":{"type":"string"},"source":{"type":"string","enum":["stored_profile","tracking_snapshot","tracking_history","public_cache","live"]},"asOf":{"type":["string","null"],"format":"date-time"},"creditsUsed":{"type":"integer","minimum":0},"warnings":{"type":"array","items":{"type":"string"}},"coverage":{"type":"string","enum":["partial","unknown","complete"],"description":"complete requires authoritative evidence; page end alone is insufficient."},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["requestId","source","asOf","creditsUsed","warnings","hasMore","nextCursor"],"additionalProperties":false},"ListMeta":{"type":"object","properties":{"requestId":{"type":"string"},"source":{"type":"string","enum":["stored_profile","tracking_snapshot","tracking_history","public_cache","live"]},"asOf":{"type":["string","null"],"format":"date-time"},"creditsUsed":{"type":"integer","minimum":0},"warnings":{"type":"array","items":{"type":"string"}},"coverage":{"type":"string","enum":["partial","unknown","complete"],"description":"complete requires authoritative evidence; page end alone is insufficient."},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}},"required":["requestId","source","asOf","creditsUsed","warnings","hasMore","nextCursor","coverage"],"additionalProperties":false},"Person":{"type":"object","properties":{"id":{"type":"string","description":"Stable Instagram account ID, always a string."},"username":{"type":["string","null"]},"fullName":{"type":["string","null"]},"avatarUrl":{"type":["string","null"],"format":"uri"},"isPrivate":{"type":["boolean","null"]},"isVerified":{"type":["boolean","null"]}},"required":["id","username","fullName","avatarUrl","isPrivate","isVerified"],"additionalProperties":false},"Profile":{"type":"object","properties":{"id":{"type":"string","description":"Stable Instagram account ID, always a string."},"username":{"type":"string"},"fullName":{"type":["string","null"]},"avatarUrl":{"type":["string","null"],"format":"uri"},"isPrivate":{"type":["boolean","null"]},"isVerified":{"type":["boolean","null"]},"followerCount":{"type":["integer","null"],"minimum":0},"followingCount":{"type":["integer","null"],"minimum":0},"trackedLists":{"type":"array","items":{"type":"string","enum":["followers","following"]}}},"required":["id","username","fullName","avatarUrl","isPrivate","isVerified","followerCount","followingCount","trackedLists"],"additionalProperties":false},"PeopleList":{"type":"object","properties":{"accountId":{"type":"string"},"username":{"type":"string"},"availableCount":{"type":["integer","null"],"minimum":0,"description":"Readable observed list size, not the profile total. null if unknown."},"returnedCount":{"type":"integer","minimum":0},"items":{"type":"array","items":{"$ref":"#/components/schemas/Person"}}},"required":["accountId","username","availableCount","returnedCount","items"],"additionalProperties":false},"Changes":{"type":"object","properties":{"accountId":{"type":"string"},"username":{"type":"string"},"list":{"type":"string","enum":["followers","following"]},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"timezone":{"type":"string"},"summary":{"type":"object","properties":{"added":{"type":["integer","null"],"description":"null when observations are insufficient.","minimum":0},"removed":{"type":["integer","null"],"description":"null when observations are insufficient.","minimum":0},"netDiscovered":{"type":["integer","null"],"description":"null when observations are insufficient."},"countNetChange":{"type":["integer","null"],"description":"null when observations are insufficient."}},"required":["added","removed","netDiscovered","countNetChange"],"additionalProperties":false},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["new_follower","lost_follower","new_follow","unfollow"]},"detectedAt":{"type":"string","format":"date-time","description":"Detection time, not exact Instagram action time."},"account":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":["string","null"]}},"required":["id","username"],"additionalProperties":false}},"required":["id","kind","detectedAt","account"],"additionalProperties":false}}},"required":["accountId","username","list","from","to","timezone","summary","items"],"additionalProperties":false},"Tracking":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"},"fullName":{"type":["string","null"]},"avatarUrl":{"type":["string","null"],"format":"uri"},"status":{"type":"string","enum":["active","paused","archived"]},"trackedLists":{"type":"array","items":{"type":"string","enum":["followers","following"]}},"followerCount":{"type":["integer","null"],"minimum":0},"followingCount":{"type":["integer","null"],"minimum":0},"profileAsOf":{"type":["string","null"],"format":"date-time"},"listSnapshots":{"type":"object","properties":{"followers":{"type":["string","null"],"format":"date-time"},"following":{"type":["string","null"],"format":"date-time"}},"required":["followers","following"],"additionalProperties":false}},"required":["id","username","fullName","avatarUrl","status","trackedLists","followerCount","followingCount","profileAsOf","listSnapshots"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false},"ProfileResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Profile"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"],"additionalProperties":false},"ListResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PeopleList"},"meta":{"$ref":"#/components/schemas/ListMeta"}},"required":["data","meta"],"additionalProperties":false},"ChangesResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Changes"},"meta":{"$ref":"#/components/schemas/ListMeta"}},"required":["data","meta"],"additionalProperties":false},"TrackingResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tracking"},"meta":{"$ref":"#/components/schemas/PagedMeta"}},"required":["data","meta"],"additionalProperties":false},"QueryRequest":{"type":"object","properties":{"username":{"type":"string","pattern":"^@?[A-Za-z0-9_][A-Za-z0-9_.]{0,29}$"},"type":{"type":"string","enum":["profile","followers","following"]},"maxCredits":{"type":"integer","minimum":1,"maximum":1000},"cursor":{"type":"string","description":"Online cursor from POST /queries only; not permitted for profile."}},"required":["username","type","maxCredits"],"additionalProperties":false,"allOf":[{"if":{"properties":{"type":{"const":"profile"}},"required":["type"]},"then":{"not":{"required":["cursor"]}}}]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"meta":{"type":"object","properties":{"requestId":{"type":"string"},"creditsUsed":{"type":["integer","null"],"minimum":0,"description":"Confirmed logical-operation cost, or null when unsettled."}},"required":["requestId","creditsUsed"],"additionalProperties":false}},"required":["error","meta"],"additionalProperties":false}}}}