Build Guide · Stack · Prompt ·
Stop Flying Blind

Instagram Studio

I was copying numbers out of the Instagram app by hand and still couldn't tell which hooks worked. So I built a private dashboard. It pulls every post's real stats from Meta's API, transcribes every reel on my laptop, scores each post 0 to 100 against my others, and shows which hook types and topics win. Here's the whole build, so you can make your own.

How To Use This Page

Want to build it today? Get your token in Step 01, then paste The Prompt into Claude Code. Want to understand it first? Start with What You're Building and read top to bottom.

11
Numbers Per Reel
0–100
Score For Every Post
1
Prompt To Start
Before You Build

A Dashboard Doesn't Post For You.

Build this in a weekend, then go back to posting. Tuning charts for a month instead of shipping content is Building Theater: it feels like progress and it grows nothing.

The Solo Founder Lab · Opening Soon

I'm building a place where you learn to build products that work like a real company's on your own, and get them in front of people who pay, with a CTO who's built two seven-figure software companies in your corner.

Lab.exeWaitlist Open

Measure. Then Make More.

  • Live product teardowns. Your app, your landing page and your content, reviewed in front of everyone.
  • Weekly CTO office hours. Live, hot-seat style. Bring the API error Meta's docs won't explain.
  • Launch Pad. When you launch, the room shows up.
  • The 30-Day Launch Plan. Validate, plan, build and launch, one week at a time. Members only.

Free to join the waitlist. Opens at $49/mo, and the price goes up as seats fill, so first in pays the least.

What You're Building

Four Parts, One Password.

The Short Version

A website only you can open. A sync job asks Instagram for every post and its numbers and saves them in a Postgres database. A script on your laptop downloads each reel, transcribes it and has Claude label the hook. The dashboard scores every post against your others and groups the scores by what you did.

What It Shows You

Your top and bottom 10%. Average score by hook type, topic, length, call to action, weekday and time posted. A full list you can sort by any number, colored green and magenta by how each one compares. And a page per post with every stat, its transcript and labels you can fix by hand.

Why Not Just Use The App

Instagram shows one post at a time and never compares them. You can't sort 180 reels by skip rate, or ask which hook type gets shared most. Once the numbers are in your own database, you can.

The Stack

Six Tools, Mostly Free.

You don't need my website to build this. Here's every piece, what it does in Studio, and what it costs. If a term is new, the "Why" line is the one to read.

Next.js + TypeScriptApp

The website and its API.

Next.js is a React framework that serves pages and API routes from one project. TypeScript is JavaScript with types, so your agent catches its own mistakes before you do.

Why
One codebase for the dashboard, the sync route and the label API. Claude Code writes it well.
Cost
Free.
VercelHosting

Where the website runs.

Connect a GitHub repo and every push deploys. It holds your secrets as environment variables and can call your sync route on a schedule.

Why
Built by the Next.js team, so there's nothing to configure. Each pull request gets its own preview link.
Cost
Hobby is free for personal projects. Pro is $20/mo if it's for a business.
NeonDatabase

Postgres that sleeps when you do.

A hosted Postgres database. It scales to zero when nobody's using it and wakes up when you open the page, which suits a dashboard you check a few times a week.

Why
Real SQL, a connection string Vercel understands, and the free plan holds years of posts.
Cost
Free plan.
Instagram Graph APIData

Your real numbers.

Meta's official API. With a token for your own account, it lists every post and returns its insights: views, reach, skip rate, watch time, shares and more.

Why
No scraping, no third-party analytics tool, and the numbers match the app.
Cost
Free. Needs a Business or Creator account.
Whisper + ffmpegYour Mac

Transcripts, on your laptop.

Whisper is OpenAI's open-source speech-to-text model. ffmpeg pulls the audio and the first frame out of each video. Both run locally.

Why
Free, private, and no video files on a server. The small model is about 460 MB.
Cost
Free.
Claude CodeYour Mac

The builder, and the labeler.

You build Studio with it. Then its command line, claude -p, reads each transcript and first frame and returns the hook, on-screen text, hook type and topic as JSON.

Why
Runs on your Claude subscription, so labeling 180 reels costs nothing extra.
Cost
A Claude Pro or Max plan.
01 · The Meta Token

Get A Key To Your Own Numbers.

This is the step that takes longest, because Meta's dashboards move around a lot. Your Instagram account must be public and set to Business or Creator. There are two kinds of token. Pick one.

Path A · Instagram LoginEasiest

Ten minutes, no Facebook Page.

  1. Go to developers.facebook.com/apps and choose Create app. Pick the Other use case, then the Business app type. Skip connecting a business portfolio.
  2. Under Add products, choose Set up on Instagram. That adds API setup with Instagram business login.
  3. There, add your Instagram account, then choose Generate token next to it and sign in to Instagram.
  4. Allow only instagram_business_basic and instagram_business_manage_insights.
  5. Copy the token (it starts with IG) straight into your .env.local.
Lasts
60 days. Your sync can renew it for another 60 once it's a day old, so it never lapses as long as the sync runs.
Host
graph.instagram.com
Path B · System UserNever Expires

An hour, and it never needs renewing.

  1. Link your Instagram account to a Facebook Page, and have a business portfolio at business.facebook.com.
  2. Create the app as in Path A, and add it to the portfolio.
  3. In Business Settings, go to Users, then System users, and add one.
  4. Assign it the Facebook Page and the app, with the Develop app permission on the app.
  5. Choose Generate token, pick the app, set expiry to Never, and allow only instagram_basic, instagram_manage_insights, pages_show_list and pages_read_engagement.
Lasts
Forever. The token starts with EAA.
Host
graph.facebook.com. Your account is found through the Page: /me/accounts.
No App Review

Development mode is fine.

Standard Access covers accounts you own. You don't need App Review, business verification or a live app to read your own insights.

The Gotcha That Cost Me An Hour

Check which Facebook profile you're in.

If Business Settings doesn't show your Page, you may be signed in as a different Facebook profile. Switch profiles in the top corner, then assign the Page to the system user.

Read-Only

Ask for less.

Leave out publishing, comments and messages. A token that can only read can't post for you if it ever leaks.

Check.Token
# Path A: should print your username
curl "https://graph.instagram.com/v27.0/me?fields=username,account_type&access_token=$IG_ACCESS_TOKEN"

# Path B: should list your Page with an instagram_business_account id
curl "https://graph.facebook.com/v27.0/me/accounts?fields=name,instagram_business_account&access_token=$IG_ACCESS_TOKEN"
Keep It Secret

Paste the token into .env.local and your host's environment variables, nowhere else. Not into a chat, a doc or a commit. If it ends up somewhere it shouldn't, make a new one and revoke the old one.

02 · The Numbers

What Instagram Will Tell You.

Two calls do all the work. /{account}/media lists every post, 50 at a time. /{post-id}/insights returns its numbers. Here's every number a reel gives you, and what I use it for.

MetricUnitWhat it meansIn the score
viewsCountTimes it was played, replays included.Reach
reachCountAccounts that saw it at least once.Reach, and the base for every rate
ig_reels_video_view_total_timemsTotal time everyone spent watching it.Reach
reels_skip_rate%Share of views that swiped away in the first 3 seconds. The same number the app shows.Retention (lower is better)
ig_reels_avg_watch_timemsHow long the average view lasted.Retention
sharesCountSends to a DM or a story.Engagement, per account reached
likesCountLikes.Engagement, per account reached
savedCountSaves to a collection.Engagement, per account reached
repostsCountReposts to the viewer's own profile.Engagement, per account reached
commentsCountComments, including the ones a "comment for the link" call to action brings in.Engagement, per account reached
total_interactionsCountLikes, saves, comments and shares added up.Stored, not scored
Get.Posts
GET /v27.0/me/media
  ?fields=id,media_type,caption,
    permalink,media_url,thumbnail_url,
    timestamp,is_shared_to_feed
  &limit=50

# Follow paging.next until it's gone.
Get.Insights
GET /v27.0/{post-id}/insights
  ?metric=views,reach,likes,comments,
    saved,shares,reposts,
    total_interactions,
    ig_reels_avg_watch_time,
    ig_reels_video_view_total_time,
    reels_skip_rate
Feed.PostsCarousels

Photos and carousels differ.

No watch time or skip rate. You get the shared counts plus follows and profile_visits, which reels don't report. Score each format only against itself.

Quirk 01

One bad metric fails the call.

Ask for a metric Instagram won't give for that post and the whole request errors. When a batch fails, retry each metric alone, keep what works, and skip the refused one for the rest of the run.

Quirk 02

Trial reels aren't flagged.

There's no "trial" field. But a trial reel is never on your grid, so is_shared_to_feed: false is the tell. Score trials against trials: they only reach non-followers.

Quirk 03

Some videos won't download.

Reels with licensed music come back with no media_url. Usually they're music with text on screen, so label those from the cover and caption instead.

Quirk 04

File links expire.

media_url and thumbnail_url stop working after a few days. Fetch a fresh link right before you download a video, and don't cache thumbnails as if they were permanent.

Quirk 05

Numbers move for a week.

A reel gets most of its views in its first few days. After day 7 it gains well under 1% a day. So freeze each post's numbers at 7 days, and compare everything at that age.

Also Available

Account insights.

Follower count, when your followers are online, profile views, website clicks and audience demographics. I don't use them yet, but they're one call away.

03 · Database And Hosting

Three Tables And A Sync Route.

Store the raw numbers and work out scores when the page loads. Then a change to the scoring never needs a migration, and you can always rescore history.

Schema.sql
-- One row per post. Numbers as JSON, so a new
-- metric is a new key, not a new column.
create table if not exists studio_posts (
  id text primary key,
  media_type text not null,
  caption text, permalink text, thumbnail_url text,
  posted_at timestamptz not null,
  shared_to_feed boolean,  -- false = trial reel
  metrics jsonb,           -- latest
  metrics_7d jsonb,        -- frozen at 7 days
  synced_at timestamptz,
  duration_sec real, transcript text,
  hook text, on_screen_text text,
  hook_type text, topic text,
  labeled_at timestamptz,  -- by the script
  edited_at timestamptz    -- fixed by hand
);

-- The numbers per post per day, for growth curves.
create table if not exists studio_snapshots (
  post_id text references studio_posts(id) on delete cascade,
  taken_on date, metrics jsonb not null,
  primary key (post_id, taken_on)
);

-- The token, so the sync can renew it.
create table if not exists studio_settings (
  key text primary key, value text not null,
  updated_at timestamptz not null default now()
);
Setup.StepsOnce

From zero to a live, locked page.

  1. Neon. Create a project at console.neon.tech. Copy the pooled connection string as DATABASE_URL, and the direct one as DATABASE_URL_UNPOOLED for migrations.
  2. Schema. Save the SQL as a file and run it with a small script against the direct URL. Write every change as alter table … add column if not exists so it's safe to run again.
  3. GitHub + Vercel. Push the repo, import it at vercel.com/new, and add the environment variables below.
  4. First sync. Deploy, then call the sync route once by hand. The first run fetches every post, so it's the slowest.
Env
DATABASE_URL, IG_ACCESS_TOKEN, STUDIO_PASSWORD (long and random), CRON_SECRET (openssl rand -hex 32), and IG_USER_ID only if a Path B token sees more than one account.
The Lock

One password, not a login system.

Entering STUDIO_PASSWORD sets an httpOnly cookie holding a SHA-256 hash of it. Every page and server action checks the cookie. Change the password and every browser is signed out. Keep /studio out of robots.txt and your sitemap.

The Sync

A route that only machines can call.

GET /api/studio/sync needs Authorization: Bearer $CRON_SECRET. It lists posts, then fetches insights six at a time. Posts under 60 days old refresh every run; older ones once a week. Give the route a 300-second limit.

When It Runs

By hand, or on a schedule.

I run it as the first step of the label script, so one command after posting does everything. Want it automatic? A Vercel cron is three lines in vercel.json, and Vercel sends CRON_SECRET with each call for you.

Run.Sync
# By hand
curl -H "Authorization: Bearer $CRON_SECRET" \
  https://YOUR-SITE.com/api/studio/sync

# Or daily at 11:00 UTC: vercel.json
{ "crons": [{ "path": "/api/studio/sync",
              "schedule": "0 11 * * *" }] }
Freeze.At.7.DaysSQL
-- Save today's numbers. The first time a post is
-- 7+ days old, keep them as its scoring numbers.
update studio_posts set
  metrics = $2::jsonb,
  metrics_7d = case
    when metrics_7d is not null then $2::jsonb || metrics_7d
    when $3 then $2::jsonb  -- $3: age >= 7 days
  end,
  synced_at = now()
where id = $1;
04 · Transcripts And Labels

Whisper Listens. Claude Labels.

Scores tell you which posts won. Labels tell you why. A script on your laptop asks the site which posts have no label, then does five things to each one. Your server never touches a video file.

Label.PipelinePer Post
  1. Download. Ask the site for a fresh media_url and save the video to a temp folder.
  2. Extract. ffmpeg pulls 16 kHz mono audio, the length, and the frame at half a second.
  3. Transcribe. Whisper's small model, with the caption as its prompt so it spells your names and tools right.
  4. Label. claude -p reads the timed transcript, the caption and the frame, and returns JSON against a schema.
  5. Send back. POST the label to the site with the same bearer secret, then delete the temp folder.
Gets
The hook (the first three seconds, word for word), the text on screen, one of ten hook types, and a 1 to 3 word topic that reuses your existing topics where it can.
Install.Mac
# Once
brew install ffmpeg
python3 -m venv ~/whisper-venv
~/whisper-venv/bin/pip install openai-whisper

# What the script runs, per reel
ffmpeg -i video.mp4 -vn -ac 1 -ar 16000 audio.wav
~/whisper-venv/bin/python3 -m whisper audio.wav \
  --model small --language en --fp16 False \
  --output_format json \
  --initial_prompt "$CAPTION"

# The label, as JSON that matches a schema
claude -p "$PROMPT" --output-format json \
  --json-schema "$SCHEMA" \
  --allowedTools Read --add-dir "$TMP"
Hook.Types10

Bold claim, Contrarian, Question, Number list, Tool reveal, Result first, Pain point, Story, How-to, Other.

Each gets a one-line definition and an example in the prompt. Fewer, clearer types make better patterns than many fuzzy ones.

Why.Local✣

Whisper needs more memory and time than a serverless function gets. On your laptop it's free, private and fast enough to run while you do something else.

The first run downloads the model once.

Hand.EditsWin

Whisper will mishear things. Each post's page lets you fix the hook, labels and transcript. Those edits set edited_at, and a rerun of the script never overwrites them.

05 · The Score

50 Is A Typical Post.

Every number becomes a percentile among your other posts of the same format, so a 0.8% share rate and a 45% skip rate land on the same 0 to 1 scale. Then three groups, blended. My first version scored my best reels in the 20s, so test yours against posts you know did well.

Reach · 50%How Far
Views
25%
Accounts reached
25%
Views vs usual
25%
Total watch time
25%

"Usual" is the median views of your previous 20 posts. It keeps an early post that beat a smaller account from losing to every later, bigger one.

Retention · 25%Held Them
Skip rate
50%
Average watch time
33%
Replays (views ÷ reach)
17%

Skip rate is ranked lowest-is-best. It leads because, across my trial reels, it predicted how far a reel went better than anything else.

Engagement · 25%Acted
Shares
33%
Likes
27%
Saves
20%
Reposts
13%
Comments
7%

Each one per account reached, weighted in the order Instagram seems to value them. Comments come last because "comment for the link" inflates them.

Lesson 01

Rates alone get it wrong.

A reel that reaches strangers rarely keeps a follower-sized like rate. Score only on rates and your viral posts sink to the middle. Reach has to be in the score.

Lesson 02

Reach is one signal.

Views, accounts reached and total watch time rank posts almost identically. Weighting them differently changes nothing, so don't spend an afternoon tuning them.

Lesson 03

Trials only meet trials.

Trial reels go to non-followers, so their views and like rates run far below a normal reel's. Rank their retention and engagement against other trials, or every one looks like a flop.

Patterns

Average the score by what you did.

Hook type, topic, length, whether the caption asks for a comment, weekday and time posted. Grey out any group under 3 posts. One lucky reel isn't a pattern.

Window

Let yourself ignore the past.

A slider limits everything to the last N days. If your account changed a lot, last spring's posts shouldn't decide what works now.

Color

Green and magenta, by fifths.

Top fifth strong green, bottom fifth strong magenta, the middle left plain. Always print the number on top, so nobody has to read color alone.

The Prompt

Build Yours From Scratch.

Make an empty folder, open Claude Code in it, and paste this. It builds Studio one step at a time, stops whenever you need to click something in a dashboard, and shows you each piece working before it moves on.

Studio.Build.Prompt
You're helping me build "Studio": a private dashboard that scores every post on my Instagram and shows me which hooks and topics work. I'm [not an engineer / a developer], so explain each step in plain words before you do it.

My account: [@handle], a [Business or Creator] account. I post about [your niche].
My computer: [Mac with Apple Silicon / Windows / Linux]
My token: [Instagram Login, starts "IG" / System User, starts "EAA"]. It's in .env.local as IG_ACCESS_TOKEN.

The stack. Don't swap any of these without asking:
- Next.js (App Router) and TypeScript, deployed on Vercel from GitHub
- Neon Postgres, through the pg package
- The Instagram Graph API v27.0, read-only
- Whisper and ffmpeg on my computer for transcripts, and the claude CLI for labels

Build it in this order. After each step, show me it working and wait for my OK.

1. Skeleton. A Next.js app with a page at /studio, locked by one password in STUDIO_PASSWORD. Entering it sets an httpOnly cookie holding a SHA-256 hash of the password, checked on every page and server action. No user accounts and no auth library. Keep /studio out of robots.txt and the sitemap.

2. Database. A schema.sql with three tables: studio_posts (id, media_type, caption, permalink, thumbnail_url, posted_at, shared_to_feed, metrics jsonb, metrics_7d jsonb, synced_at, duration_sec, transcript, hook, on_screen_text, hook_type, topic, labeled_at, edited_at), studio_snapshots (post_id, taken_on, metrics) and studio_settings (key, value, updated_at). Idempotent SQL, plus a script that applies it with DATABASE_URL_UNPOOLED.

3. Sync. GET /api/studio/sync, allowed only with "Authorization: Bearer" plus CRON_SECRET, with a 300 second limit:
   - List every post: id, media_type, caption, permalink, media_url, thumbnail_url, timestamp, is_shared_to_feed. Follow paging.
   - Fetch insights, six posts at a time. Reels: views, reach, likes, comments, saved, shares, reposts, total_interactions, ig_reels_avg_watch_time, ig_reels_video_view_total_time, reels_skip_rate. Other posts: the shared ones plus follows and profile_visits.
   - If a batch fails, retry each metric alone and skip any Instagram refuses for the rest of the run.
   - Save today's numbers and a daily snapshot. The first time a post is 7+ days old, freeze its numbers in metrics_7d.
   - Refresh posts under 60 days old every run, older ones weekly.
   - "IG" tokens: graph.instagram.com/me, renewed with refresh_access_token once a week. "EAA" tokens: graph.facebook.com, finding the account through /me/accounts, or IG_USER_ID.

4. Score, in one TypeScript module with tests. For each post, use metrics_7d (or today's numbers, marked "early", if it's under 7 days). Turn every input into a percentile among matured posts of the same format, and for trial reels (is_shared_to_feed false) among other trials, except views, reach and total watch time. Score = 50% reach (views, reach, views divided by the median of the previous 20 posts, total watch time, equal weights) + 25% retention (skip rate 3, lower is better; average watch time 2; views per account reached 1) + 25% engagement per account reached (shares 5, likes 4, saves 3, reposts 2, comments 1). Skip any input a post doesn't have and reweight the rest.

5. Dashboard. Filters for the last N days and hiding trial reels, kept in the URL. Headline stats, my top and bottom 10%, average score by hook type, topic, length, call to action, weekday and time posted (greyed under 3 posts), and a full table sortable by every column with a sticky header. Color each number by fifths: strong green for the top fifth, light green, none, light magenta, strong magenta for the bottom. Use thumbnails; Instagram's image links expire, so plain img tags.

6. Labels. GET and POST /api/studio/labels behind the same secret: GET returns unlabeled posts with a fresh media_url, plus the hook types and topics already in use. Then scripts/label.mjs, run on my computer: call the sync first, then for each post download the video, use ffmpeg for 16 kHz mono audio, the duration and a frame at 0.5s, transcribe with Whisper small (caption as the initial prompt), and run claude -p with a JSON schema to return hook, onScreenText, hookType (from a fixed list of 10 with definitions) and topic (reuse existing topics). POST it back and delete the temp files. Videos with no media_url get labeled from the cover image.

7. Post page. /studio/[id] with every number, its percentile, the transcript, and a form to fix the hook, on-screen text, hook type, topic and transcript. A hand edit sets edited_at, and the label script never overwrites a field I set by hand.

Rules:
- Never print my token, password or secrets. Read them from .env.local, and give me the list of environment variables to add on Vercel myself.
- Read-only on Instagram. Never ask for publishing, comment or message permissions.
- Before each step, tell me the plan in 3 to 5 bullets and wait.
- When something needs me (Meta, Neon or Vercel dashboards), tell me exactly where to click.
Pink Means Edit Me

Fill in your handle, your niche, your computer and your token type. Leave the rest as it is.

Token First

Do Step 01 before you paste this. It's the one part your agent can't do for you.

Change The Weights Later

Start with mine. Once you have data, look at your five best-known posts and ask the agent why each one ranks where it does.

Your Own Hook Types

Edit the list of ten to match how you think about your content, then relabel. Change it again later and relabel again.

Lessons

What I'd Tell Myself On Day One.

Note 01

Check the score against posts you remember.

Before you trust any pattern, find your five most-viewed reels in the full list. If they're not near the top, the score is wrong, not your memory. Mine were, the first time.

Note 02

Store raw numbers, score on the fly.

I changed the scoring four times in two days. Because the database only holds what Instagram said, every change rescored every post instantly.

Note 03

Don't build a login system.

It's a dashboard for one person. One long password and a hashed cookie is enough. The time goes into the score instead.

Note 04

Keep video off the server.

Transcribing on your laptop means no storage bill, no timeouts and no copies of your videos anywhere new. Only text goes to the database.

Note 05

Let your fixes win.

The labeler is good, not perfect. Make every label editable, and make sure a rerun can't undo what you fixed.

Note 06

Then go post.

The point is the next reel. Look at your top 10%, copy what they open with, and check back in a week.

One More Thing

Tools Are The Easy Part.

Anybody can build software now. Not everybody can build a business.

The Solo Founder Lab

Reading about tools is a great way to feel busy. The Lab is for Founders who'd rather get customers: weekly office hours with a CTO who's built two seven-figure software companies, and a room of other Founders who care whether anybody buys what you're making.

Lab.exe✣

Less Theater. More Customers.

Want my 30-Day Launch Plan? It's for Lab members only: validate, plan, build and launch, one week at a time.

See The Solo Founder Lab ▶