StoriesFly: Instagram and TikTok data

storiesfly

TypeScript client for the StoriesFly API. It reads public Instagram and TikTok data over HTTP. For Instagram: profiles, stories, highlights, posts, reels, comments, followers, hashtags, places and search. For TikTok: profiles, videos, stories, followers and following lists, reposts, and video download without the watermark. You do not log in to Instagram or TikTok and you do not handle cookies or sessions. You send an API key and pay per request. The same data works inside ChatGPT and Claude through the StoriesFly MCP server: see Use it from ChatGPT and Claude (MCP).

The package has no runtime dependencies. It needs Node 18 or newer (it uses the global fetch), it is ESM only, and it ships its own types. The 46 data calls and the free account call each have a method, and every answer is typed.

Install

npm install storiesfly

Get a key

1. Sign in with Telegram at https://storiesfly.com/developers/dashboard.
2. Create a key there. A new account gets 100 free requests, so you can try every call before you pay.

Keep the key on your server. Anyone who has it can spend your balance.

Quick start

The stories an account has up right now:

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(${stories.length} stories up from account ${user.id}); for (const story of stories) { console.log(story.media_type, story.taken_at_iso, story.media_url); }

Things to know:

• An account is named by { username } or { id }, never both. A post is named by { url }, { code } or { id }. The types enforce this.
• Ids are strings. Instagram ids pass 2^53, and a JSON number would round them.
• Field names are snake_case, as the API sends them. A value the answer does not carry is null. It is never 0 or "".
• Media links in answers are signed Instagram CDN links. They expire within days, so download what you need soon.

A post, with the links to its pictures and video:

const post = await client.post.get({ url: "https://www.instagram.com/p/DcyLOLIEdy7/" });

console.log(post.caption, post.likes); for (const item of post.media) { console.log(item.type, item.video_url ?? item.image_url); // one item per slide of a carousel }

A TikTok video without the watermark, and a TikTok account's followers:

const video = await client.tiktok.video({ url: "https://www.tiktok.com/@khaby.lame/video/7697307919943060767" });

console.log(video.caption, video.views, video.video_url); // video_url has no watermark

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

for await (const page of client.paginate(client.tiktok.user.followers, { username: "khaby.lame" }, { maxPages: 2 })) { for (const follower of page.users) console.log(follower.username); }

Options

new StoriesFly({

apiKey: "...", // required, sent as X-Api-Key baseUrl: "...", // default https://storiesfly.com/api/v1 fetch: myFetch, // default: the global fetch timeoutMs: 60_000, // per attempt; 0 turns the timeout off maxRetries: 2, // for rate_limited answers; 0 turns retries off });

Every call also takes a last argument with signal (an AbortSignal), timeoutMs, maxRetries and withMeta.

Paging

A call that returns a list returns one page, with next_cursor and has_more. client.paginate follows the list for you. It is an async iterator that calls the method, yields the page, then calls it again with the next_cursor of the page before, until has_more is false:

for await (const page of client.paginate(client.user.followers, { username: "instagram" }, { maxPages: 4 })) {

for (const follower of page.users) console.log(follower.username); }

• Every page is one call and is charged as one. A large account has many pages, so set maxPages unless you mean to read the whole list.
• paginate takes the method itself (client.user.followers), its parameters, and options: maxPages, signal and withMeta. A cursor in the parameters starts the walk from a page you already have.
• Only methods that take cursor can be paginated, and the compiler refuses the rest. The Paged column of the methods table marks them, and ENDPOINTS (exported) has a paged flag on each.
• To page by hand, pass next_cursor back as cursor and keep every other parameter the same. A cursor is opaque. A cursor the API did not return gives bad_request.
• Page size follows Instagram and varies by endpoint. The spec fixes it for three: user.posts returns up to 9 items a page, user.followers and user.following up to 25. The Paged column of the methods table shows the size wherever the spec gives one.

TikTok

TikTok calls live under client.tiktok. An account is named by { username }.

await client.tiktok.video({ url });                          // one video or photo post, short links too

await client.tiktok.user.profile({ username }); // followers, following, likes, video count await client.tiktok.user.videos({ username }); // newest first, paged await client.tiktok.user.stories({ username }); // stories up now await client.tiktok.user.followers({ username }); // paged await client.tiktok.user.following({ username }); // paged await client.tiktok.user.reposts({ username }); // paged

• videos, followers, following and reposts take cursor and return next_cursor, so client.paginate follows them. Page size follows TikTok and varies by endpoint.
• An account that hides its followers or following list answers an empty page with hidden: true.
• A number is null when it is not exact. File links are temporary: save the files right away.
• On a later page of tiktok.user.videos, video_url is null. To get the file of one video, call tiktok.video or download with its url.

Download

client.download({ url }) takes the link of an Instagram post, reel or IGTV, or of a TikTok video or photo post (short links too), and returns the file links: the video (TikTok's without the watermark), every picture of a carousel or photo post, the cover, and for TikTok the soundtrack. It returns files only; for the numbers use post.get or tiktok.video. The price is fixed per call: $0.50 per 1,000 for an Instagram link and $0.20 per 1,000 for a TikTok link.

const { platform, media } = await client.download({ url: "https://www.instagram.com/reel/DdY3MUJCfby/" });

for (const file of media) console.log(file.type, file.url);

File links are temporary, so download them right away. client.account() also shows the download prices as download_price_usd.

Use it from ChatGPT and Claude (MCP)

The same data is available to AI assistants at https://storiesfly.com/mcp, with no code. Details: https://storiesfly.com/developers/mcp.

• 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.

What a call cost: response meta

A call resolves to the parsed body. To see the billing headers too, pass { withMeta: true } as the last argument and the call resolves to { data, meta }:

const { data, meta } = await client.user.profile({ username: "instagram" }, { withMeta: true });

console.log(data.followers); console.log(meta.unitsCharged, meta.balanceRemaining, meta.freeUnitsRemaining);

A header the answer did not carry is null. The meta is returned per call and not kept on the client (there is no lastResponse), so calls that run at the same time cannot overwrite each other's numbers. With paginate, { withMeta: true } yields { data, meta } for each page.

Errors and what is charged

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

import { StoriesFly, StoriesFlyError } from "storiesfly";

try { await client.user.stories({ username: "some_private_account" }); } catch (err) { if (!(err instanceof StoriesFlyError)) throw err;

console.log(err.status); // HTTP status; 0 when no answer came console.log(err.code); // "private_account" console.log(err.requestId); // quote it to support console.log(err.retryAfterMs); // from Retry-After, when the API sent one console.log(err.meta?.unitsCharged); // what this failed call was charged }

Other fields: fields (with bad_request, the names of the refused parameters), linkUrl (with telegram_required, the link that links your account to Telegram), url (the URL called; it holds no key) and body (the parsed error body).

You are charged for answers: a 200, not_found and private_account. A wrong parameter, a rate limit and an empty balance cost nothing, and a failure on our side is refunded. err.meta.unitsCharged and X-Units-Charged say what a call took.

The client adds three codes of its own, with status 0 when no answer came: timeout (no answer within timeoutMs), network_error (fetch failed; the error has the cause) and invalid_response (an answer that is not in the documented shape, such as a proxy's error page; the status and the body are kept).

Retries

• A 429 is retried up to maxRetries times (2 by default). The client waits for the Retry-After the API sent, or half a second and then longer when it sent none. A Retry-After longer than 30 seconds is not waited out: the error is thrown at once, with retryAfterMs set.
• A 402 is never retried: another call would not change it.
• Other errors, timeouts and network errors are not retried. A 500 or 503 is refunded, so you can retry it yourself.

Pricing

From $1.50 per 1,000 requests, prepaid. See https://storiesfly.com/developers/pricing.

One unit is one request. Every call takes 1 unit, a page of a list included. Resolving a share link takes 2, and `ac