Guides / Developers

Get Instagram Story Insights with the Graph API

This guide shows how to read the insights of Instagram Stories in your own code. It covers what you need, the two API calls, a short Node.js example, and the limits that stop many first attempts.

Updated November 7, 2026

What you need

The Instagram Graph API gives story insights only for professional accounts. Before you start, get these items:

  1. An Instagram professional account (Business or Creator) that is linked to a Facebook Page.
  2. A Meta app with the permissions that Meta requires for Instagram insights, such as instagram_basic and instagram_manage_insights.
  3. An access token for that app. For a first test, the Graph API Explorer on Meta for Developers gives you one.
  4. The Instagram account id. Call GET /me/accounts?fields=instagram_business_account with the token to find it.

Keep the token on your server. Do not send it to a browser, and do not put it in a file that you commit.

The two API calls

1. List the live stories. This call returns the stories that the account posted in the last 24 hours:

GET https://graph.facebook.com/v25.0/{ig-user-id}/stories
    ?fields=id,media_type,timestamp,permalink
    &access_token={token}

2. Read the insights of one story. Ask for the four story metrics in one call:

GET https://graph.facebook.com/v25.0/{story-id}/insights
    ?metric=views,reach,replies,shares
    &access_token={token}

The answer has one row for each metric. Each slide of a story sequence is a separate story with its own id and its own numbers. For what each metric means, read Instagram Story insights explained.

A Node.js example

Storylink publishes a free, open-source client for these calls: @storylinkpro/instagram-stories-api. It is typed, it has no dependencies, and it needs Node 20 or later. Install it:

npm install @storylinkpro/instagram-stories-api

This script prints the views, reach and replies of each live story:

import { createClient } from "@storylinkpro/instagram-stories-api";

const ig = createClient({
  accessToken: process.env.INSTAGRAM_ACCESS_TOKEN,
  igUserId: process.env.INSTAGRAM_USER_ID,
});

for (const story of await ig.stories()) {
  const { views, reach, replies } = await ig.storyInsights(story.id);
  console.log(story.id, views, reach, replies);
}

The package also has a command line. This command lists the live stories without an install:

npx @storylinkpro/instagram-stories-api stories

The source code is on GitHub, under the MIT license.

Limits to plan for

  • The 24-hour window. The API gives story metrics only while the story is live. After that, you cannot ask for the numbers of that story.
  • Missing numbers. Meta withholds some story numbers when very few people saw the story. A missing number is not zero. The client returns it as null.
  • Rate limits. Meta limits how many calls an app and an account can make. When you get a rate-limit error, wait before you call again.
  • Token expiry. A token can expire or be revoked. Meta then answers with error code 190, and you must get a new token.

Keep the numbers after the story expires

Because of the 24-hour window, save the numbers while the story is live. A simple way is a scheduled job that runs every hour:

  1. List the live stories.
  2. Read the insights of each story.
  3. Save the numbers with the story id and the time of the reading.

The numbers grow during the 24 hours. Use the last reading before the story expires as the final value for the story.