Updated October 2026. Originally published on storiesfly.com.

This post builds one in Node.js: poll the stories of a list of accounts, remember which story ids you have already seen, save the media, and send a Telegram message for each new story. It also works out the cost per day, because polling is billed per request and the interval is the number you control.

Code was type-checked against storiesfly 1.1.0 (ESM, Node 18 or newer, no runtime dependencies). If you want the result without writing code, see the last section.

What you need

• A StoriesFly API key. Sign in with Telegram at storiesfly.com/developers/dashboard. A new account gets 100 free requests.
• A Telegram bot token from @BotFather, and the chat id the messages should go to. Send your bot a message, then open https://api.telegram.org/bot<token>/getUpdates to see the chat id.

npm install storiesfly
export STORIESFLY_API_KEY="your_key"
export TELEGRAM_BOT_TOKEN="123456:ABC..."
export TELEGRAM_CHAT_ID="123456789"

You never log in to Instagram with your own account. You send an API key, and your account never appears among a story's viewers.

What the stories call returns

import { StoriesFly } from "storiesfly";

const client = new StoriesFly({ apiKey: process.env.STORIESFLY_API_KEY! });

const { user, stories } = await client.user.stories({ username: "instagram" });

console.log(user.id, stories.length);
console.log(stories[0]);

Output shape (values are illustrative):

{
  "id": "3012345678901234567",
  "url": "https://www.instagram.com/stories/instagram/3012345678901234567/",
  "taken_at": 1793000000,
  "taken_at_iso": "2026-10-28T09:30:00.000Z",
  "media_type": "video",
  "media_url": "https://...",
  "thumbnail_url": "https://...",
  "video_duration": 12.4
}

stories is empty when the account has none up. Ids are strings, which matters: Instagram ids are larger than 2^53 and a JSON number would round them. Always store and compare them as strings.

The polling script

The logic is a diff: fetch the stories that are up now, drop the ids you have already seen, alert on the rest, save the new ids.

import { readFile, writeFile } from "node:fs/promises";
import { StoriesFly, StoriesFlyError, type Story } from "storiesfly";

const client = new StoriesFly({ apiKey: process.env.STORIESFLY_API_KEY! });

const ACCOUNTS = ["instagram", "natgeo"];
const INTERVAL_MS = 30 * 60 * 1000; // every 30 minutes
const SEEN_FILE = "./seen-stories.json";

type Seen = Record<string, string[]>; // username -> story ids

async function loadSeen(): Promise<Seen> {
  try {
    return JSON.parse(await readFile(SEEN_FILE, "utf8")) as Seen;
  } catch {
    return {};
  }
}

async function notify(username: string, story: Story): Promise<void> {
  const text = [
    `New ${story.media_type} story from @${username}`,
    story.taken_at_iso ?? "",
    story.media_url ?? story.url ?? "",
  ]
    .filter(Boolean)
    .join("\n");

  const res = await fetch(`https://api.telegram.org/bot${process.env.TELEGRAM_BOT_TOKEN}/sendMessage`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ chat_id: process.env.TELEGRAM_CHAT_ID, text }),
  });
  if (!res.ok) console.error("Telegram error", res.status, await res.text());
}

async function checkAccount(username: string, seen: Seen): Promise<void> {
  const { stories } = await client.user.stories({ username });
  const known = new Set(seen[username] ?? []);
  const fresh = stories.filter((s) => !known.has(s.id));

  // Oldest first, so the chat reads in order.
  fresh.sort((a, b) => (a.taken_at ?? 0) - (b.taken_at ?? 0));
  for (const story of fresh) await notify(username, story);

  // Keep only ids that are still up, so the file does not grow forever.
  seen[username] = stories.map((s) => s.id);
}

async function runOnce(): Promise<void> {
  const seen = await loadSeen();
  for (const username of ACCOUNTS) {
    try {
      await checkAccount(username, seen);
    } catch (err) {
      if (err instanceof StoriesFlyError) {
        console.error(`@${username}: ${err.code} (request ${err.requestId})`);
        if (err.code === "credits_exhausted") return; // stop until you top up
      } else {
        throw err;
      }
    }
  }
  await writeFile(SEEN_FILE, JSON.stringify(seen));
}

await runOnce();
setInterval(() => void runOnce(), INTERVAL_MS);

Notes on the choices in that script:

• First run. Everything that is up when you start counts as new, so you get one batch of alerts. To avoid that, run once with the notify call commented out, then turn it back on.
• Why store only ids that are still up. A story lives about 24 hours, so there is no reason to remember an id longer. The file stays small.
• Errors. A private account answers private_account and a missing one not_found. Both are charged, so remove such usernames from the list rather than polling them forever. rate_limited is retried by the client twice before it reaches your catch.
• One failure does not stop the others. The try is inside the loop over accounts.
• Order of writes. The seen file is written after the alerts, so a crash between the two can send a duplicate alert. That is the safer direction compared with missing one.

Cron instead of setInterval

A long-running setInterval is fine on a VPS. If you prefer cron, drop the last line (setInterval) and run the script once per tick:

*/30 * * * * cd /path/to/project && node poll.mjs >> poll.log 2>&1

Cron survives restarts and leaves nothing running between ticks. If you compile the script from TypeScript, point cron at the compiled .js file.

Save the media soon

The media_url values are signed links, and they expire within days. A story is gone from the account after a day, and the file link does not last much longer. If you want to keep it, download it when the alert fires:

import { mkdir, writeFile } from "node:fs/promises";
import type { Story } from "storiesfly";

export async function saveStory(username: string, story: Story): Promise<string | null> {
  if (!story.media_url) return null;

  const res = await fetch(story.media_url);
  if (!res.ok) return null;

  const ext = story.media_type === "video" ? "mp4" : "jpg";
  await mkdir(`./stories/${username}`, { recursive: true });
  const path = `./stories/${username}/${story.id}.${ext}`;
  await writeFile(path, Buffer.from(await res.arrayBuffer()));
  return path;
}

Call saveStory(username, story) next to notify. If you would rather get the file in Telegram than a link, the Bot API has sendVideo and sendPhoto, which take a URL.

What it costs

Each client.user.stories call is one request, and requests start from $1.50 per 1,000. The cost is accounts x polls per day:

The interval is the lever. Stories stay up for a day, so polling every 30 to 60 minutes still catches each one with hours to spare. Polling every minute only buys you earlier alerts, not more of them. A good rule is to poll busy accounts often and quiet ones rarely: keep two lists with two intervals.

Two things cost nothing to check. Your balance (client.account() is free) and the per-call charge (pass { withMeta: true } and read meta.unitsCharged). Add a guard that stops the script when balanceRemaining falls below a number you pick. It comes as a string in US dollars, so compare Number(meta.balanceRemaining).

Privacy, in one paragraph

You never log in with your own account, so your account never appears among a story's viewers. The person is not notified. The script reads public stories only: a private account gives private_account, and you cannot get around that.

Limits to know about

• It only sees stories that are up now. There is no history, so if the script was down for two days, you missed those stories.
• It detects a story at the next poll, not at the moment it is posted. The delay is at most your interval.
• Highlights are a separate call (client.user.highlights), not part of this script.

If you do not want to run this yourself

The script above is a few dozen lines, but you have to host it, keep the bot token safe and watch the balance. If you only want the alerts, StoriesFly has a Telegram bot and a tracker that does this without code: you add an account and get a message when it posts. The API is the better fit if you want the data inside your own app.

FAQ

How do I get the Instagram story API without logging in?

Use an API key from the dashboard and call client.user.stories({ username }). There is no Instagram login, cookie or session on your side.

Can I look up an account by id?

Yes. client.user.stories({ id }) takes an id instead of a username. Pass one of the two, never both.

How often should I poll?

Every 30 to 60 minutes is enough for most uses, since a story stays up for a day.

Will the account know I looked?

The person is not notified.

Do the media links last?

No. They expire within days, so save the files when you get the alert.

Full method list and response types: storiesfly.com/developers/docs.

Updated October 2026. Originally published on storiesfly.com.

TL;DR: pick by need (as of 2026-10-28)

What Meta's official API is

Meta's Instagram Platform overview describes two setups:

• Instagram API with Instagram Login. App users sign in with Instagram credentials, no Facebook Page is needed, and requests go to graph.instagram.com. Scopes are the instagram_business_* family. See the setup page.
• Instagram API with Facebook Login. App users sign in with Facebook, the account must be linked to a Facebook Page, and requests go to graph.facebook.com.

Both serve Instagram professional accounts: business or creator accounts. The Instagram Login page lists comment moderation, content publishing, media insights, mentions and messaging as what the API is for.

Basic Display is gone. Meta's announcement says that starting on December 4th, 2024 the API is no longer available and all its requests fail, and that after that date there is no set of Instagram APIs for consumer developer apps. Meta points business and creator use cases to the two setups above.

Official API: can and cannot

"Own" means accounts whose owners connected to your app and granted permissions.

Rate limits: most endpoints use Instagram Business Use Case limits, where calls in 24 hours equal 4800 times the account's impressions, counted per app and app user pair. Business Discovery and Hashtag Search use Platform Rate Limits instead (overview).

Two takeaways. First, Business Discovery is genuinely useful for a quick look at another professional account's counts and recent media, but it is an aggregate view. Second, anything that touches accounts you don't own at scale comes with review and verification steps, and tokens that depend on a signed-in app user.

When you need public data from accounts you don't own

If your job is "look up this username and give me data", the official API does not fit, and no amount of configuration changes that. This is where a REST API for public data fits.

StoriesFly is a REST API that reads public Instagram and TikTok data. You never log in to Instagram, and your own account never appears among a story's viewers. The person is not notified. You send an API key and pay per request: from $1.50 per 1,000 requests, prepaid, and 100 free requests once per Telegram account.

Install the official client (storiesfly 1.1.0, Node 18+, ESM, no runtime dependencies):

npm install storiesfly

import { StoriesFly, StoriesFlyError } from "storiesfly";

const client = new StoriesFly({ apiKey: process.env.STORIESFLY_API_KEY! });

async function main() {
  try {
    const profile = await client.user.profile({ username: "instagram" });
    console.log(profile.username, profile.followers, profile.is_private);

    // First 3 pages of followers: up to 25 per page, one request per page.
    for await (const page of client.paginate(client.user.followers, { username: "instagram" }, { maxPages: 3 })) {
      for (const user of page.users) console.log(user.username);
    }

    const { stories } = await client.user.stories({ username: "instagram" });
    for (const s of stories) console.log(s.media_type, s.taken_at_iso, s.media_url);

    const { media } = await client.download({ url: "https://www.instagram.com/reel/DdY3MUJCfby/" });
    for (const file of media) console.log(file.type, file.url);
  } catch (err) {
    if (err instanceof StoriesFlyError && err.code === "private_account") {
      console.log("Private account: no data.");
      return;
    }
    throw err;
  }
}
main();

Get a key by signing in with Telegram at storiesfly.com/developers/dashboard. Full method list: docs and the OpenAPI spec. Beyond profiles, followers and stories, the client has calls for posts, reels, comments, hashtags, places and search, plus TikTok profiles, videos and lists.

Honest limits:

• Private accounts return private_account, and that answer is charged like any answer. The API reads public data only.
• Media links expire. Links in answers are signed CDN links that last days, not months. Download what you need soon.
• Lists are paged. A page of followers holds up to 25 accounts and costs one request. Always set maxPages, or paginate walks the list to its end. For a verified account, Instagram shows only about 50 followers and no next page.
• Stories are live ones. user.stories returns what is up right now. It is not an archive.
• Numbers can be null. A value the answer doesn't carry is null, never 0.

Use the same data from ChatGPT or Claude (MCP)

The same data is available to AI assistants through an MCP server, with no code. In Claude Code:

claude mcp add --transport http storiesfly https://storiesfly.com/mcp

ChatGPT and Claude connect to the same address and sign in with Telegram. Details: storiesfly.com/developers/mcp.

Check the rules that apply to you

This is not legal advice. Use public data only. Before you build, read Instagram's and Meta's terms and the privacy law that applies to your use and your users, such as rules on storing personal data, retention and deletion requests. Decide what you keep, for how long, and why.

FAQ

Can the official Instagram API return the follower list of another account?

Not in the documented fields. Business Discovery returns followers_count and media for another Business or Creator account, and its page does not mention follower lists.

Is there still a way to read a personal account's feed through Meta's API?

No. Basic Display ended on 2024-12-04, and Meta says there is no set of Instagram APIs for consumer developer apps after that date.

Do I need App Review and Business Verification?

For serving professional accounts you don't own or manage, Meta's overview says Advanced Access is needed, which requires App Review and Business Verification. For your own account, Standard Access applies.

Do I log in to Instagram with StoriesFly?

No. You send an API key. You never log in with your own account, and your account never appears among a story's viewers.

What happens on a private account?

The call returns private_account and no data. Only public data is available.

Not affiliated with Instagram or Meta. Facts about Meta's API were checked against developers.facebook.com on 2026-10-28; docs change, so check the linked pages before you build.

Updated October 2026. Originally published on storiesfly.com.

This post shows a working approach in Node.js with the storiesfly npm client: install, page through a list, dedupe it, save a snapshot, and diff it on the next run to see who followed and who left. It also covers hidden lists, private accounts, error codes and what it costs.

Everything below was type-checked against storiesfly 1.1.0. It is ESM and needs Node 18 or newer (it uses the global fetch) and has no runtime dependencies.

Install and get a key

npm install storiesfly

Sign in with Telegram at storiesfly.com/developers/dashboard and create a key. A new account gets 100 free requests, so you can run everything here before paying. Keep the key on the server and read it from the environment:

export STORIESFLY_API_KEY="your_key"

You do not log in to TikTok and you do not handle cookies. The key is the only credential.

One page of followers

A list call returns one page. Here is the shape:

import { StoriesFly } from "storiesfly";

const client = new StoriesFly({ apiKey: process.env.STORIESFLY_API_KEY! });

const page = await client.tiktok.user.followers({ username: "khaby.lame" });

console.log(page.users.length, page.has_more, page.next_cursor, page.hidden);
console.log(page.users[0]);

The output looks like this (values are illustrative):

{
  "user": { "username": "khaby.lame" },
  "users": [
    {
      "id": "6812345678901234567",
      "sec_uid": "MS4wLjABAAAA...",
      "username": "some.follower",
      "full_name": "Some Follower",
      "profile_pic_url": "https://...",
      "verified": false,
      "is_private": false,
      "followers": 120,
      "following": 310,
      "likes": 4500,
      "videos": 12
    }
  ],
  "total": null,
  "hidden": false,
  "next_cursor": "...",
  "has_more": true
}

A few things to know about the fields. Every number can be null when it is not exact, so do not treat null as zero. username can also be null in a list entry, which matters for dedupe. total is the size of the whole list when it is known, and it is often not.

Walk the whole list

client.paginate calls the method, yields the page, then calls it again with the previous next_cursor until has_more is false. Set maxPages unless you really mean to read everything, because each page is a billed request.

import { StoriesFly, type TikTokUserShort } from "storiesfly";

const client = new StoriesFly({ apiKey: process.env.STORIESFLY_API_KEY! });

export async function fetchList(
  method: typeof client.tiktok.user.followers | typeof client.tiktok.user.following,
  username: string,
  maxPages: number,
): Promise<{ users: TikTokUserShort[]; hidden: boolean; complete: boolean }> {
  const byId = new Map<string, TikTokUserShort>();
  let hidden = false;
  let complete = true;

  for await (const page of client.paginate(method, { username }, { maxPages })) {
    if (page.hidden) {
      hidden = true;
      break;
    }
    for (const u of page.users) {
      const key = u.id ?? u.sec_uid ?? u.username;
      if (key) byId.set(key, u);
    }
    complete = !page.has_more;
  }

  return { users: [...byId.values()], hidden, complete };
}

const followers = await fetchList(client.tiktok.user.followers, "khaby.lame", 10);
console.log(followers.users.length, followers.complete ? "whole list" : "stopped at maxPages");

Two details in there are worth explaining.

Dedupe. Keep a Map keyed by id, falling back to sec_uid and then username. Lists are read while accounts follow and unfollow, so an entry can appear on two pages, and a plain array would count it twice.

complete. The loop ends either because the list ended (has_more is false) or because it hit maxPages. Those are different outcomes. If you diff a truncated list against a full one, every account past the cut looks like an unfollow. Track whether you got the whole list and refuse to diff when you did not.

The same function reads the other direction: pass client.tiktok.user.following instead of followers. Lists are paged and how deep they go varies by account, so check complete rather than assuming.

Detect new followers and unfollows

Save the ids from one run, load them on the next, and compare. A JSON file is enough to start with.

import { readFile, writeFile } from "node:fs/promises";
import { StoriesFly } from "storiesfly";

const client = new StoriesFly({ apiKey: process.env.STORIESFLY_API_KEY! });
const username = "khaby.lame";
const file = `./followers-${username}.json`;

async function loadSeen(): Promise<Record<string, string> | null> {
  try {
    return JSON.parse(await readFile(file, "utf8")) as Record<string, string>;
  } catch {
    return null; // first run
  }
}

const current: Record<string, string> = {};
let complete = true;
for await (const page of client.paginate(client.tiktok.user.followers, { username }, { maxPages: 20 })) {
  if (page.hidden) throw new Error("This account hides its followers list");
  for (const u of page.users) {
    const key = u.id ?? u.sec_uid ?? u.username;
    if (key) current[key] = u.username ?? "";
  }
  complete = !page.has_more;
}

const previous = await loadSeen();
if (previous && complete) {
  const joined = Object.keys(current).filter((id) => !(id in previous));
  const left = Object.keys(previous).filter((id) => !(id in current));
  console.log(`new: ${joined.length}, gone: ${left.length}`);
  for (const id of joined) console.log("+", current[id] || id);
  for (const id of left) console.log("-", previous[id] || id);
}

if (complete) await writeFile(file, JSON.stringify(current));
else console.warn("List was cut at maxPages. Snapshot not saved.");

Output on the second run:

new: 2, gone: 1
+ some.follower
+ another.one
- someone.who.left

Some honest limits of this approach:

• It sees who is in the list now compared with last time. It cannot tell you when someone followed, only that they were not there on the previous run.
• Someone who follows and unfollows between two runs is invisible. Shorten the interval if that matters.
• An account that renames itself keeps its id, which is why the snapshot is keyed by id and stores the username only for display.

Run it from cron, once a day for most accounts.

Hidden lists and private accounts

Some accounts hide their followers or following list. The call still succeeds and returns an empty page with hidden: true. Check that flag before you treat an empty list as "no followers". In the code above, the diff throws instead of saving an empty snapshot, because an empty snapshot would make everyone look like a new follower the day the list becomes visible.

Private accounts are separate. To check one before you spend requests on its list, read the profile first, which is one request:

import { StoriesFly } from "storiesfly";

const client = new StoriesFly({ apiKey: process.env.STORIESFLY_API_KEY! });

const profile = await client.tiktok.user.profile({ username: "khaby.lame" });
console.log(profile.followers, profile.following, profile.is_private);

if (profile.is_private) {
  console.log("Private account, skipping");
}

The profile gives followers and following, which is a good guide to the size of a list, so you can estimate the cost before you paginate. Either number can be null when TikTok does not give an exact one, so treat it as a hint and not as a promise. A call that reaches a private account can also come back as a private_account error, which is charged (see below).

Error handling

Every call that does not return data throws StoriesFlyError. Test code, not message.

import { StoriesFly, StoriesFlyError } from "storiesfly";

const client = new StoriesFly({ apiKey: process.env.STORIESFLY_API_KEY! });

try {
  const page = await client.tiktok.user.followers({ username: "no_such_account_12345" });
  console.log(page.users.length);
} catch (err) {
  if (!(err instanceof StoriesFlyError)) throw err;

  switch (err.code) {
    case "not_found":
      console.error("No such account");
      break;
    case "private_account":
      console.error("Private account");
      break;
    case "credits_exhausted":
      console.error("Top up your balance");
      break;
    case "rate_limited":
      console.error(`Slow down, retry in ${err.retryAfterMs ?? "a few"} ms`);
      break;
    case "upstream_unavailable":
      console.error("Not available right now, retry shortly");
      break;
    default:
      console.error(err.status, err.code, err.requestId);
  }
  console.error("charged:", err.meta?.unitsCharged);
}

What matters in practice:

• rate_limited is retried for you, twice by default, using the Retry-After the API sends. You only see it if the retries run out.
• credits_exhausted is never retried. Another call would not change it.
• upstream_unavailable and internal_error are refunded, so retrying them yourself is safe.
• not_found and private_account are charged, because the call got an answer. A bad parameter (bad_request), a rate limit and an empty balance cost nothing.
• Keep err.requestId in your logs. Support can find a call with it.

What it costs

Pricing is from $1.50 per 1,000 requests, prepaid. Every call is one request, and that includes each page of a list. So the cost of reading a list is the number of pages, not the number of followers.

requests = ceil(list size / page size)
cost     = requests x $0.0015

Page size follows TikTok and varies, so measure it with one real call before you plan a budget. As an illustration only: if a page held 50 accounts, a 10,000-follower list would be 200 requests, about $0.30. A daily snapshot of that account for a month is about $9. The profile call above usually gives you the list size (when it is not null), so you can do this arithmetic per account before you commit.

To see exactly what a call charged, pass { withMeta: true } as the last argument and read meta.unitsCharged and meta.balanceRemaining. With paginate, you get { data, meta } for every page.

Reposts

The videos an account reposted come through the same paging pattern:

import { StoriesFly } from "storiesfly";

const client = new StoriesFly({ apiKey: process.env.STORIESFLY_API_KEY! });

for await (const page of client.paginate(client.tiktok.user.reposts, { username: "khaby.lame" }, { maxPages: 2 })) {
  for (const v of page.videos) {
    console.log(v.author.username, v.url, v.views, v.likes);
  }
}

Each item has the video's author, caption, cover, views and likes. comments and shares are null here, and taken_at is when the author posted the video, not when it was reposted. An empty list means the account has no reposts or hides them.

The same thing from Claude or ChatGPT, no code

If you only need an answer once, you can skip the script. The same data is available to AI assistants over MCP:

claude mcp add --transport http storiesfly https://storiesfly.com/mcp

ChatGPT and Claude connect to the same address and sign in with Telegram. Then ask in plain language, for example "list the first pages of followers of this TikTok account and tell me which ones are verified". Details are at storiesfly.com/developers/mcp. It is a good way to try a question before you turn it into a script.

FAQ

Do I need a TikTok login or cookies?

No. You send an API key and nothing else.

Can I get the full followers list of any account?

Lists are paged and depth varies by account. Check has_more to see whether you reached the end, and hidden to see whether the account hides the list.

What happens with a private account?

Check is_private on the profile first. A call that reaches a private account may answer private_account, and that answer is charged.

How do I know who unfollowed?

Compare two complete snapshots, as above. The API returns the current list, not a history.

How do I stay inside a budget?

Always set maxPages, check the profile counts first, and skip the diff when complete is false.

Is the free tier real?

A new account gets 100 free requests, once. After that you prepay a balance.

Full method list and response types: storiesfly.com/developers/docs. The client's source and README are in the npm package.