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 support@instoryview.com

Before you start#

Create an API Key#

Read a follower snapshot#

Read the response#

Endpoints#