Quickstart

Create an API Key, read a follower snapshot you already have, then make your first budgeted online query.

Before you start

You need an Instoryview account and a way to send HTTPS requests. The examples use curl.

Base URL: https://instoryview.com/open-api/v1
Authentication: Authorization: Bearer YOUR_API_KEY
Format: JSON
Contract: OpenAPI 3.1 document

Create an API Key

The secret is shown only once. Copy it into your terminal environment or a secret manager — never into a public frontend, a repository or a shared conversation.

A new Key can read existing data. Online queries are a separate permission that you turn on yourself; see Authentication and credits.

Read a follower snapshot

For an account whose followers you track, this request returns your latest available snapshot. It does not start another scan or spend new collection credits.

Terminal

export INSTORYVIEW_API_KEY='YOUR_API_KEY'
curl 'https://instoryview.com/open-api/v1/accounts/alice/followers' \
  -H "Authorization: Bearer $INSTORYVIEW_API_KEY"

Replace alice with an Instagram username. For an account you have never tracked, the API can return reusable public query data; when none exists, it returns an explicit error instead of an empty list.

Read the response

JSON

{
  "data": {
    "accountId": "123456789",
    "username": "alice",
    "availableCount": 850,
    "returnedCount": 1,
    "items": [
      {
        "id": "987654321",
        "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",
    "coverage": "partial",
    "creditsUsed": 0,
    "warnings": ["partial_list"],
    "hasMore": true,
    "nextCursor": "OPAQUE_CURSOR"
  }
}

These values are made up. Check source, asOf and coverage before you describe a result.

Field	Meaning
`data.availableCount`	Members observed in this snapshot. Not the profile's follower total.
`data.returnedCount`	Members on this page.
`meta.source`	Where the data came from, such as `tracking_snapshot` or `public_cache`.
`meta.asOf`	When the list was observed, not when you sent the request.
`meta.coverage`	`partial` means the list does not establish complete Instagram coverage.
`meta.creditsUsed`	Credits this request spent. Reading existing data spends `0`.
`meta.nextCursor`	Send it back as `cursor` for the next page. `null` once the available pages end.

Endpoints

The five GET endpoints read existing data. An empty wallet does not block an otherwise authorized read; request limits and data permissions still apply.

Query fresh public data

First allow online queries on your Key and set a daily API budget (it starts at 0). Each query needs an integer maxCredits from 1 to 1000 and an Idempotency-Key header. Here 2 is a spending cap, not a fixed price, and the query returns one page: a first list page reads the profile and then the page, 1 credit each.

Terminal

curl 'https://instoryview.com/open-api/v1/queries' \
  -H "Authorization: Bearer $INSTORYVIEW_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: REPLACE_WITH_A_UNIQUE_REQUEST_ID' \
  --data '{"username":"bob","type":"followers","maxCredits":2}'

Online queries can read public accounts you have never tracked, and they never start tracking. Read permissions, budgets and retries before you automate paid queries.

Questions about the API? Email [email protected]

Before you start#

Create an API Key#

Read a follower snapshot#

Read the response#

Endpoints#