{"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 meta.nextCursor from the previous page of this same endpoint, account and credential. Valid for about one hour.","schema":{"type":"string","maxLength":8192}}],"responses":{"200":{"description":"Stored data. No new collection charge.","headers":{"Cache-Control":{"schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"schema":{"type":"string"},"description":"Same value as meta.requestId. Quote it when you contact support."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackingResponse"},"example":{"data":{"items":[{"id":"123456789","username":"sample_creator","fullName":"Sample Creator","avatarUrl":null,"isPrivate":false,"isVerified":false,"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 (no retained snapshot of this list), data_unavailable (no stored or reusable public data) or not_found (the account does not exist, is private, or was removed from Instoryview). 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 (the username belongs to two accounts you track, or a cursor names another account) or data_changed (the data or your access changed while paging): read the first page again.","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. On POST /queries also query_interrupted: the original operation stopped and was settled; only confirmed source calls were charged and it never runs again.","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"}},"X-Request-Id":{"schema":{"type":"string"},"description":"Same value as meta.requestId. Quote it when you contact support."}},"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 (no retained snapshot of this list), data_unavailable (no stored or reusable public data) or not_found (the account does not exist, is private, or was removed from Instoryview). 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 (the username belongs to two accounts you track, or a cursor names another account) or data_changed (the data or your access changed while paging): read the first page again.","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. On POST /queries also query_interrupted: the original operation stopped and was settled; only confirmed source calls were charged and it never runs again.","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 meta.nextCursor from the previous page of this same endpoint, account and credential. Valid for about one hour.","schema":{"type":"string","maxLength":8192}}],"responses":{"200":{"description":"Stored data. No new collection charge.","headers":{"Cache-Control":{"schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"schema":{"type":"string"},"description":"Same value as meta.requestId. Quote it when you contact support."}},"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 (no retained snapshot of this list), data_unavailable (no stored or reusable public data) or not_found (the account does not exist, is private, or was removed from Instoryview). 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 (the username belongs to two accounts you track, or a cursor names another account) or data_changed (the data or your access changed while paging): read the first page again.","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. On POST /queries also query_interrupted: the original operation stopped and was settled; only confirmed source calls were charged and it never runs again.","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 meta.nextCursor from the previous page of this same endpoint, account and credential. Valid for about one hour.","schema":{"type":"string","maxLength":8192}}],"responses":{"200":{"description":"Stored data. No new collection charge.","headers":{"Cache-Control":{"schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"schema":{"type":"string"},"description":"Same value as meta.requestId. Quote it when you contact support."}},"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 (no retained snapshot of this list), data_unavailable (no stored or reusable public data) or not_found (the account does not exist, is private, or was removed from Instoryview). 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 (the username belongs to two accounts you track, or a cursor names another account) or data_changed (the data or your access changed while paging): read the first page again.","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. On POST /queries also query_interrupted: the original operation stopped and was settled; only confirmed source calls were charged and it never runs again.","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. The cursor fixes the observation context: for the next page send only cursor (and limit). An account you never tracked returns 403 list_not_authorized.","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","description":"Not needed with a cursor: the cursor keeps the list, dates and timezone.","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 meta.nextCursor from the previous page of this same endpoint, account and credential. Valid for about one hour.","schema":{"type":"string","maxLength":8192}}],"responses":{"200":{"description":"Stored data. No new collection charge.","headers":{"Cache-Control":{"schema":{"type":"string","const":"private, no-store"}},"X-Request-Id":{"schema":{"type":"string"},"description":"Same value as meta.requestId. Quote it when you contact support."}},"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 (no retained snapshot of this list), data_unavailable (no stored or reusable public data) or not_found (the account does not exist, is private, or was removed from Instoryview). 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 (the username belongs to two accounts you track, or a cursor names another account) or data_changed (the data or your access changed while paging): read the first page again.","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. On POST /queries also query_interrupted: the original operation stopped and was settled; only confirmed source calls were charged and it never runs again.","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, including for an untracked account. One page is one source page: usually 25 people, about 50 for a verified account's follower list, which has no further pages. Requires both scopes and a positive maxCredits. Each source call costs 1 credit: a profile 1; a first list page 2 (it reads the profile first), so a first list page with maxCredits below 2 is refused before any call; a next page 1. At most 5 pages per list (page_limit_reached). No implicit tracking or full export. Each online next page is a new logical operation with a new idempotency key and 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"}},"X-Request-Id":{"schema":{"type":"string"},"description":"Same value as meta.requestId. Quote it when you contact support."}},"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: the request cannot fit its own cap (a first list page needs at least 2), the shared daily budget (0 until you set one in Developer settings) or the 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 (no retained snapshot of this list), data_unavailable (no stored or reusable public data) or not_found (the account does not exist, is private, or was removed from Instoryview). 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 and keep the original key: within about 15 minutes the operation is settled (confirmed source calls are charged, calls that got no answer are not), and the same key then returns 503 query_interrupted. account_changed here means the username now belongs to another Instagram account than the one Instoryview knew; send the query again with a new key to read the current one. creditsUsed is null while the cost is not settled.","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. On POST /queries also query_interrupted: the original operation stopped and was settled; only confirmed source calls were charged and it never runs again.","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"},"description":"Machine-readable notes, empty when there are none: partial_list (a list is not proven complete), cached_page_only (reusable public data holds one page), page_limit_reached (the online paging ceiling), list_unavailable (Instagram returned no members although the profile counts some; not an empty list), username_reused (another account has used this username; check the id), detected_changes_only and report coverage notes on changes. New codes can be added."},"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"},"description":"Machine-readable notes, empty when there are none: partial_list (a list is not proven complete), cached_page_only (reusable public data holds one page), page_limit_reached (the online paging ceiling), list_unavailable (Instagram returned no members although the profile counts some; not an empty list), username_reused (another account has used this username; check the id), detected_changes_only and report coverage notes on changes. New codes can be added."},"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"},"description":"Machine-readable notes, empty when there are none: partial_list (a list is not proven complete), cached_page_only (reusable public data holds one page), page_limit_reached (the online paging ceiling), list_unavailable (Instagram returned no members although the profile counts some; not an empty list), username_reused (another account has used this username; check the id), detected_changes_only and report coverage notes on changes. New codes can be added."},"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","description":"Absolute signed link to the latest known profile picture, valid for about a day. Do not store it; read the account again for a fresh link."},"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","description":"Absolute signed link to the latest known profile picture, valid for about a day. Do not store it; read the account again for a fresh link."},"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","description":"Absolute signed link to the latest known profile picture, valid for about a day. Do not store it; read the account again for a fresh link."},"isPrivate":{"type":"boolean"},"isVerified":{"type":"boolean"},"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","isPrivate","isVerified","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}}}}