API reference

Every endpoint of the Instoryview Open API on one page, generated from the same contract the API is built on.

Version 1.0.0 · OpenAPI 3.1Raw JSON

Base URL and authentication

Base URL: https://instoryview.com/open-api/v1

Send your API Key in the Authorization header on every request:

HTTP

GET /open-api/v1/tracking
Authorization: Bearer YOUR_API_KEY

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.

Response format

Every response is JSON with two parts: data, described with each endpoint below, and meta. An error has an error object instead of data, with the same meta.

Fields of meta

Name	Type	Description
`requestId`required	string
`source`required	string	One of: `stored_profile`, `tracking_snapshot`, `tracking_history`, `public_cache`, live.
`asOf`required	date-time \| null
`creditsUsed`required	integer
`warnings`required	string[]	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`required	string	complete requires authoritative evidence; page end alone is insufficient. One of: partial, unknown, complete.
`hasMore`required	boolean
`nextCursor`required	string \| null

Error response

JSON

{
  "error": {
    "code": "snapshot_unavailable",
    "message": "No retained readable follower snapshot is available."
  },
  "meta": {
    "requestId": "req_error_example",
    "creditsUsed": 0
  }
}

List my tracked accounts

GET/open-api/v1/tracking

Stored readsScopes:data:read

Defaults to active and paused accounts. Counts and snapshot timestamps are included per account. No fresh provider calls.

Parameters

Name	In	Type	Description
`includeArchived`	query	boolean	Include readable removed tracking records. Default false.
`limit`	query	integer	Items per stored read page. 1–100. Default 50.
`cursor`	query	string	Opaque `meta.nextCursor` from the previous page of this same endpoint, account and credential. Valid for about one hour. At most 8192 characters.

Response

Stored data. No new collection charge.

Fields of data

Name	Type	Description
`items`required	object[]
`items[].id`required	string
`items[].username`required	string
`items[].fullName`required	string \| null
`items[].avatarUrl`required	uri \| null	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.
`items[].isPrivate`required	boolean
`items[].isVerified`required	boolean
`items[].status`required	string	One of: active, paused, archived.
`items[].trackedLists`required	string[]
`items[].followerCount`required	integer \| null
`items[].followingCount`required	integer \| null
`items[].profileAsOf`required	date-time \| null
`items[].listSnapshots`required	object
`items[].listSnapshots.followers`required	date-time \| null
`items[].listSnapshots.following`required	date-time \| null

Example · 200

{
  "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
  }
}

Shared errors400401403404409410429500503

Read existing account profile and totals

GET/open-api/v1/accounts/{username}

Stored readsScopes:data:read

Reads stored profile or permitted reusable public data. Unknown counts are null. Profile observation time may differ from list time.

Parameters

Name	In	Type	Description
`username`required	path	string	Instagram username. Pagination remains bound to the resolved stable account ID.

Response

Stored data. No new collection charge.

Fields of data

Name	Type	Description
`id`required	string	Stable Instagram account ID, always a string.
`username`required	string
`fullName`required	string \| null
`avatarUrl`required	uri \| null	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`required	boolean \| null
`isVerified`required	boolean \| null
`followerCount`required	integer \| null
`followingCount`required	integer \| null
`trackedLists`required	string[]

Example · 200

{
  "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": []
  }
}

Shared errors400401403404409410429500503

Read an available follower snapshot

GET/open-api/v1/accounts/{username}/followers

Stored readsScopes:data:read

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.

Parameters

Name	In	Type	Description
`username`required	path	string	Instagram username. Pagination remains bound to the resolved stable account ID.
`limit`	query	integer	Items per stored read page. 1–100. Default 50.
`cursor`	query	string	Opaque `meta.nextCursor` from the previous page of this same endpoint, account and credential. Valid for about one hour. At most 8192 characters.

Response

Stored data. No new collection charge.

Fields of data

Name	Type	Description
`accountId`required	string
`username`required	string
`availableCount`required	integer \| null	Readable observed list size, not the profile total. null if unknown.
`returnedCount`required	integer
`items`required	Person[]
`items[].id`required	string	Stable Instagram account ID, always a string.
`items[].username`required	string \| null
`items[].fullName`required	string \| null
`items[].avatarUrl`required	uri \| null	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.
`items[].isPrivate`required	boolean \| null
`items[].isVerified`required	boolean \| null

Example · 200

{
  "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
  }
}

Shared errors400401403404409410429500503

Read an available following snapshot

GET/open-api/v1/accounts/{username}/following

Stored readsScopes:data:read

Same structure as followers; the following snapshot and entitlement are selected independently. Cursor must come from this endpoint and current caller.

Parameters

Name	In	Type	Description
`username`required	path	string	Instagram username. Pagination remains bound to the resolved stable account ID.
`limit`	query	integer	Items per stored read page. 1–100. Default 50.
`cursor`	query	string	Opaque `meta.nextCursor` from the previous page of this same endpoint, account and credential. Valid for about one hour. At most 8192 characters.

Response

Stored data. No new collection charge.

Fields of data

Name	Type	Description
`accountId`required	string
`username`required	string
`availableCount`required	integer \| null	Readable observed list size, not the profile total. null if unknown.
`returnedCount`required	integer
`items`required	Person[]
`items[].id`required	string	Stable Instagram account ID, always a string.
`items[].username`required	string \| null
`items[].fullName`required	string \| null
`items[].avatarUrl`required	uri \| null	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.
`items[].isPrivate`required	boolean \| null
`items[].isVerified`required	boolean \| null

Example · 200

{
  "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
  }
}

Shared errors400401403404409410429500503

Read detected tracking changes

GET/open-api/v1/accounts/{username}/changes

Stored readsScopes:data:read

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.

Parameters

Name	In	Type	Description
`username`required	path	string	Instagram username. Pagination remains bound to the resolved stable account ID.
`list`	query	string	Not needed with a cursor: the cursor keeps the list, dates and timezone. One of: followers, following. Default followers.
`from`	query	date	Inclusive start date. Requires to. Defaults to the last seven calendar days; at most 366 days.
`to`	query	date	Inclusive end date. Requires from.
`timezone`	query	string	IANA timezone that defines the date window. Default UTC.
`limit`	query	integer	Items per stored read page. 1–100. Default 50.
`cursor`	query	string	Opaque `meta.nextCursor` from the previous page of this same endpoint, account and credential. Valid for about one hour. At most 8192 characters.

Response

Stored data. No new collection charge.

Fields of data

Name	Type	Description
`accountId`required	string
`username`required	string
`list`required	string	One of: followers, following.
`from`required	date
`to`required	date
`timezone`required	string
`summary`required	object
`summary.added`required	integer \| null	null when observations are insufficient.
`summary.removed`required	integer \| null	null when observations are insufficient.
`summary.netDiscovered`required	integer \| null	null when observations are insufficient.
`summary.countNetChange`required	integer \| null	null when observations are insufficient.
`items`required	object[]
`items[].id`required	string
`items[].kind`required	string	One of: `new_follower`, `lost_follower`, `new_follow`, unfollow.
`items[].detectedAt`required	date-time	Detection time, not exact Instagram action time.
`items[].account`required	object
`items[].account.id`required	string
`items[].account.username`required	string \| null

Example · 200

{
  "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
  }
}

Shared errors400401403404409410429500503

Query fresh public account data within a budget

POST/open-api/v1/queries

Online queriesScopes:data:readdata:fetch

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.

Parameters

Name	In	Type	Description
`Idempotency-Key`required	header	string	Unique key for one logical paid query. Preserve for recovery. Same key with a different body conflicts. 8–200 characters.

Request body

Name	Type	Description
`username`required	string
`type`required	string	One of: profile, followers, following.
`maxCredits`required	integer	1–1000.
`cursor`	string	Online cursor from POST /queries only; not permitted for profile.

Example · profile

{
  "username": "sample_creator",
  "type": "profile",
  "maxCredits": 2
}

Example · followers

{
  "username": "sample_creator",
  "type": "followers",
  "maxCredits": 2
}

Example · following

{
  "username": "sample_creator",
  "type": "following",
  "maxCredits": 2
}

Example · nextPage

{
  "username": "sample_creator",
  "type": "followers",
  "cursor": "ONLINE_CURSOR",
  "maxCredits": 2
}

Response

Fresh profile or one list page. Idempotent replay returns the original total cost, without charging again.

Fields of data · Profile

Name	Type	Description
`id`required	string	Stable Instagram account ID, always a string.
`username`required	string
`fullName`required	string \| null
`avatarUrl`required	uri \| null	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`required	boolean \| null
`isVerified`required	boolean \| null
`followerCount`required	integer \| null
`followingCount`required	integer \| null
`trackedLists`required	string[]

Fields of data · List page

Name	Type	Description
`accountId`required	string
`username`required	string
`availableCount`required	integer \| null	Readable observed list size, not the profile total. null if unknown.
`returnedCount`required	integer
`items`required	Person[]
`items[].id`required	string	Stable Instagram account ID, always a string.
`items[].username`required	string \| null
`items[].fullName`required	string \| null
`items[].avatarUrl`required	uri \| null	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.
`items[].isPrivate`required	boolean \| null
`items[].isVerified`required	boolean \| null

Example · 200

{
  "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
  }
}

Errors specific to this endpoint

Status	Meaning
402	`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.
409	`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.
410	`cursor_expired` or `result_expired`. Expired results never authorize another collection with the old key.

Shared errors400401403404429500503

Errors

Branch on error.code; error.message is written for people. Quote meta.requestId when you contact support.

Status	Meaning
400	`validation_failed`: invalid username, filters or cursor. from/to must be supplied together.
401	unauthorized: credential missing, expired or revoked.
403	`insufficient_scope`, `list_not_authorized` or forbidden: current access does not authorize the resource.
404	`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.
409	`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.
410	`cursor_expired`: the stored paging context is no longer available.
429	`rate_limited`: wait before retrying.
500	internal: request could not be completed.
503	`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.