Instagram Agent
ActiveServerless AWS backend for one Instagram Creator account: it ingests Meta webhooks, tags comments and drafts replies to them and to DMs with an LLM, polls post insights on an age-decaying schedule, and serves it all through one API, plus a daily media kit that Claude and ChatGPT read over MCP.
Highlights
- $57/month DB to free tierAurora DSQL replaced an Aurora cluster that never paused under a five-minute poller; usage now fits the free tier.
- In Claude and ChatGPTThe media kit is an MCP tool AI apps sign in to with Google: read-only, one account, revocable in one deploy.
- AI drafts, a human sendsThe LLM only suggests an action and a reply. Nothing reaches Instagram without someone confirming it.
- Reach within 0.9% of appMedia kit totals were checked against Instagram's own app; adding up daily reach instead overstates it by a fifth.
Overview
The backend behind my wife’s Instagram Creator account. It started as a way to stop the Instagram Insight tablet from being the only place the account’s history lived, and grew into the one service everything else talks to.
It receives Meta’s webhooks for comments and messages, asks an LLM what each comment needs and drafts a reply, polls post and account insights on a schedule, and exposes all of it through one API. Once a day it also builds a media kit, the figures a brand asks for, which Claude and ChatGPT can read as an MCP tool. The tablet and the Insight Dashboard website are both clients of it. Everything scales to zero, so it costs close to nothing when nothing is happening.
Instagram / Meta
pushes webhooks, answers Graph API calls
Webhook → SQS → Processor
what just happened: comments, messages, LLM analysis
EventBridge → Poller
what every post looks like now: insights, followers, audience
Query API
serves the tablet, the dashboard and AI apps over MCP, and proxies writes back to Instagram
Screenshots on this page come from the dashboard and use a fictional account.
Problem
- The history lived on one tablet. Instagram only ever exposes a post’s current totals, so the daily snapshots the tablet kept were the only copy that would ever exist. A factory reset would lose them for good.
- Meta’s API fails silently. The wrong parameter shape returns HTTP 200
with an empty
data: [], never an error. A schema built on a guess would store nothing and look healthy, and a 30-day reach added up from daily rows counts a returning viewer once per day. - Scale-to-zero fights a five-minute schedule. Aurora Serverless only pauses after five minutes with no query, so a poller that touches Postgres every few minutes keeps it awake, and billed, all month.
- Replies are published under someone else’s name. An LLM can suggest, but a wrong reply or a wrong delete on a real account cannot be undone.
- Tokens are hard to replace and easy to over-grant. Losing the Instagram token means a browser consent flow that needs the account owner in person, so exactly one thing may rotate it. An AI app given the media kit must see nothing else, and lose access without logging out the tablet.
Approach
Analysis and acting are kept apart everywhere. The processor writes a
suggested action and a draft, and nothing in this repo acts on it by itself.
A write to Instagram only happens when a client calls the proxy after a
person confirms. The same split runs through the data: a decision is always
reproducible from what was stored (prompt version, policy version, raw
response), and “not measured” is null, never 0, so a gap never reads
as a real zero. The MCP tool tells the model the same thing.
I verified every Graph API behavior against the live account before designing a table around it, with a spike script whose raw responses are checked in as test fixtures.
What I built
Webhook ingestionDoneEvery webhook is signature-checked, stored twice and queued, or answered with a 500 so Meta retries.
GoalAccept Meta's webhooks for comments, messages and mentions without ever losing one, while staying fast and cheap at the edge.
The webhook Lambda sits behind a bare Function URL and does one job. It never runs FastAPI, so ingestion carries none of the API’s cold-start cost. The order of writes is what makes it safe to retry:
- Check the
X-Hub-Signature-256HMAC, rejecting forgeries with403. - Write the raw payload to S3 (safe to repeat).
- Claim the event in DynamoDB with
attribute_not_exists(event_id). - Send a small reference to SQS. If that fails, delete the claim and
return
500.
Comment analysisDoneEach comment gets a summary, sentiment, draft reply and an action you can rebuild from stored versions.
GoalTell, for every new comment, whether it needs an answer, and draft one, in a way that can be explained and retuned later.
The processor fetches the post caption, then calls Gemini with a structured
output schema. The model returns scores, a tag and a draft, but the action
the system records comes from a separate, versioned policy in code.
Thresholds can change as a new policy_version without calling the LLM
again.
Gemini output (prompt v5)
- summary, reason — always in English, for the operator
- intent, tag, sentiment — one tag from a fixed list of six
- suggested_reply — always drafted, in the commenter's language
- requires_answer, reply_score, ... — scores between 0 and 1
policy v2
- hide — intent is spam: hide, never delete, since the model can be wrong
- reply — reply_score ≥ 0.6 and requires_answer ≥ 0.5
- like — encourages conversation and adds value
- ignore — everything else
Drafts
- Chose
- A draft for every comment, scored as if none were written
- Instead of
- A draft only when a reply seems worthwhile
- Why
- People sometimes answer a comment the model would skip, and need a draft to start from. Scoring stays blind to the draft so it cannot inflate the recommendation.
@mention
- Chose
- Prefixed with the commenter's @handle when served
- Instead of
- Written into the stored draft
- Why
- A reply only notifies the commenter if it mentions them. Adding it on the way out covered every stored draft without re-running Gemini.
Translation
- Chose
- An on-demand route for the draft about to be sent
- Instead of
- An English field on every analysis
- Why
- The draft gets edited before it goes out, and a new field would need a new prompt version and a re-run of every comment.
Gemini answers live comments with 503 when it is busy, so 429s, 5xxs
and timeouts go back to SQS with a delay of 1 minute, 10 minutes, then 1
hour, and only a fourth failure is stored. Any other failure, like an
expired token, is stored as an error row straight away, since retrying it
just burns invocations. scripts/reprocess_events.py re-drives those by
error code once the cause is fixed.

Metrics pollerDoneOne five-minute tick polls whatever is due; an idle tick costs one DynamoDB read and no database work.
GoalCollect post, follower and account insights durably, often enough to measure a fresh Reel by the hour, without paying to keep a database awake.
There is one EventBridge rule and no tiers. Each tick asks every subject whether it is overdue, using fetch clocks stored on the rows themselves, so a missed tick heals itself.
| What | Interval |
|---|---|
| Media list (new post?) | 15 min |
| Follower count | 5 min while a post is under 24h old, else 30 min |
| Post insights | 5 min under 6h, then 15 min, 1h, 6h up to a month, then daily |
| Account insights + daily roll-up | 24h |
The first thing a tick does is read one DynamoDB item holding the earliest moment anything is due. Most ticks stop there (~130 ms). Due times for anything polled every 15 minutes or less snap to a shared wall-clock grid, so jobs batch onto the same ticks: a simulated quiet day reaches the database 96 times, evenly spaced, instead of ~200. Dense samples go to DynamoDB, which has no idle charge, and Postgres is written once a day.
Who collects
- Chose
- AWS polls on a schedule
- Instead of
- The tablet pushes what it fetched
- Why
- A tablet that sleeps or gets wiped cannot be the source of truth, and the end goal was a tablet with no Instagram token at all.
Gate fails
- Chose
- Fail open: a missing gate means "check properly"
- Instead of
- Fail closed
- Why
- The worst case becomes one wasted database wake, never a poller that silently stops collecting.
Post insights floor
- Chose
- Daily, never slower
- Instead of
- Decay further for old posts
- Why
- A post read less than daily copies the same value into several daily rows, and its day-over-day gain turns into a fake sawtooth.
Token ownership and proxyDoneThe token lives only in AWS; clients moderate comments and answer DMs through seven scoped proxy routes.
GoalTake the long-lived Instagram token off the tablet, without breaking the tablet's comment logic or letting a read-only client moderate.
The poller is the only identity with PutSecretValue, and refreshes the
token when fewer than 10 days remain. The token is read at runtime and never
cached across invocations. A CloudWatch alarm on TokenDaysRemaining treats
missing data as breaching, so a poller that stops running also sends an
email. It is the one alarm kept, because it is the one failure a redeploy
cannot fix.
- Lease, not reserved concurrency. The account’s Lambda quota is 10, and AWS refuses any reservation below that floor, so exclusivity comes from a conditional DynamoDB write that expires on its own.
- Meta’s JSON passes through unchanged. The tablet’s comment threading handles several undocumented Meta behaviors, and reshaping the payload would have meant porting all of it during a cutover.
- JWT scopes. The write routes need
instagram:write. Tokens minted before scopes existed still read everything and are refused only on writes: a missing claim grants nothing. - History import.
scripts/import_tablet_history.pyloads the tablet’s daily snapshots taggedsource = 'tablet', and a real poll always wins over an imported row for the same day.
Analytics APIDonePosting slots, time to 80% reach, per-post daily gain and comment quality, each one API route.
GoalAnswer questions the tablet never could, once metrics and comment analyses sit in the same database.
The routes are shaped around resources, not screens, so a UI change never needs a backend change. Derived numbers are computed on the server so the tablet and the dashboard cannot drift apart.
/metrics/timingrequires an explicit IANAtz. Buckets built on UTC hours would answer “best time to post” for the wrong country./metrics/velocityreads the dense samples and returnsnullunless sampling started before the post reached 80%, so it measures the post and not when polling began./metrics/media-dailyresolvesaudienceper post (views for a Reel, reach for a feed post), because asking for either column drops the other kind of post without an error./metrics/comment-qualityreturns acoverageblock saying how many analyses could be joined to a post, instead of quietly under-counting.


DM conversationsDoneEach incoming message re-analyses its conversation, and any outgoing message closes it.
GoalGive DMs the same review-then-act loop as comments, where the thing to judge is a whole conversation rather than one message.
Every incoming message re-reads its whole conversation under prompt dm-v1
and writes a new conversation_analyses row: an English summary, tags, a
suggested action, and a reply drafted in the customer’s language.
- What closes it: an outgoing message, sent from the Instagram app or through the API, is recorded as the reply that answers the conversation.
- Acting on it: two more proxy routes send a DM and heart a message,
under the same
instagram:writescope as comment moderation. - History: a throttled backfill script analyses conversations that arrived before this existed.

Comment tags and post ideasDoneSix fixed tags replace a free-text topic that gave 134 distinct topics for 178 comments.
GoalGroup comments by what they are, so the account can see what people ask for and turn it into the next posts.
The prompt asks for one tag per comment from a list the account owner chose: question, dish request, tried it, criticism, compliment or other. It comes from the same Gemini call, through a schema where it is required, and the draft follows a rule per tag:
- Question: answer from the caption, without inventing quantities it does not give.
- Tried it: thank them and invite a photo.
- Criticism: stay factual.
- Compliment: one line.

POST .../content-ideas hands Gemini the recent questions, dish requests,
criticism and tried-it comments, as English summaries with their captions
and never their authors, and returns 3-5 post ideas, each citing the
comments it answers. An idea that cites no real comment is dropped, and
nothing is stored.
Moving to Aurora DSQLDoneAurora DSQL behind the existing Data API seam: ~40k DPU a month, inside the free tier, and 0 when idle.
GoalStop paying ~$57 a month for a Postgres that never got to pause, without rewriting a repository or losing a row in the move.
A spike against a DSQL cluster loaded with a copy of production data measured ~40k DPU a month for the same traffic, against a free tier of 100k. The move was a run of small changes, each deployable on its own:
- An adapter,
db/dsql.py, that speaks the RDS Data API’sexecute_statementshape over an IAM-authenticated psycopg connection, so every repository ran unchanged. - DSQL next to Aurora, with a $5 monthly budget counted before credits, since DSQL has no capacity cap to stop a runaway bill.
- A baseline schema in DSQL’s dialect, and a copy script that compares an md5 over every table. Rehearsed on production data: migrated in 25 s, all 10 tables byte-identical.
- The switch, then the Aurora cluster and its code path removed.
| DSQL behaviour | How the adapter handles it |
|---|---|
| Closes connections at 60 min, and frozen Lambdas wake with dead sockets | Recycle a connection past 50 min of age or 4 min idle |
Optimistic concurrency, so conflicts surface as 40001 | Retry with backoff; retry a dropped connection for reads only, never writes |
| An open transaction is billed | Autocommit on every connection, matching the Data API |
Query API cold startsDoneImports drop from 756 to 286 ms with precompiled bytecode, and the API gets its own 1024 MB setting.
GoalCut what the dashboard waits for when the query API starts cold, since it sits behind every page load.
| Change | Effect |
|---|---|
| Precompiled bytecode in every package | query_api imports from 756 to 286 ms, measured locally on Python 3.12 |
| Query API memory from 256 to 1024 MB | A cold container took ~2.2 s to start, then ~3.8 s more opening the DSQL connection; CPU scales with memory |
The bytecode fix is the same read-only /var/task trap the
dashboard’s backend hit: the
package script deleted every __pycache__ and never compiled any. The
webhook, processor and poller stay at 256 MB, and all of it stays inside the
free tier at this traffic.
Media kitDoneA daily stored media kit that matches Instagram's app: views within 0.1%, reach within 0.9%.
GoalAnswer what a brand asks before a collaboration (reach, engagement, audience, best Reels) with figures that match Instagram's own app, without spending the Graph rate limit on every request.
The daily roll-up builds the kit and stores it whole, one row per day.
GET /accounts/{id}/media-kit reads that row and never calls Graph, so
asking for it costs no rate limit, and a figure quoted to a brand can be
rebuilt from the day it was taken.
| Section | What it holds |
|---|---|
performance | Meta’s own 30-day totals: accounts reached and engaged, views, interactions, likes, comments, saves, shares, and engagement rate (interactions over reach) |
audience | Followers by age, gender and country, unknown gender kept in. Meta’s breakdowns of the reached and engaged accounts come back empty |
top_reels | The ten Reels with the most lifetime views, with a current thumbnail added when served, since a stored CDN link expires within days |
account | Followers now and at the window’s start, and the first post’s date |
- Its own token. Tied to one account, 90 days by default, refused on every other route. Its key is derived from the shared secret and a generation number, so bumping the number revokes every media-kit token without logging out the dashboard or the tablet.
- Rate-limited at API Gateway, so a flood is turned away before it takes the Lambda concurrency the webhook needs.
Media kit over MCPDoneClaude and ChatGPT read the media kit through one read-only MCP tool, with a token scoped to it alone.
GoalLet someone ask Claude or ChatGPT about the account's reach and audience in a chat, with the model reading the real figures rather than guessing, and reaching nothing but the media kit.
POST /mcp serves one tool, get_media_kit(as_of?, top_reels?). It takes
media-kit tokens only, and the account comes from the token’s own claim, so
nothing the model sends can name another one.
AI app
Claude Code, claude.ai, Claude Desktop, ChatGPT
Pasted header
Claude Code: a minted token, sent as a Bearer header
OAuth sign-in
the chat apps: a 401 points to the dashboard, where the person signs in with Google
POST /mcp
get_media_kit, for the one account the token names
The 401 names the protected resource metadata (RFC 9728), which names
the dashboard’s backend as
the authorization server. Once the person allows the app, that backend asks
the agent to mint an ordinary media-kit token, passing the authorization
code’s id as a single-use key: a conditional DynamoDB write, so a code
mints one token, ever.
The tool’s description tells the model how to read the figures, since it will quote them to someone:
- reach counts each account once across the window;
- the audience is followers, not the accounts reached;
- gender
Uis unknown, so ”% women” without it is a different figure; - a
nullmeans Meta did not report it, never zero.
Transport
- Chose
- Streamable HTTP written out by hand: stateless, JSON only, no event stream
- Instead of
- The MCP SDK's server
- Why
- One read-only tool in a Lambda that lives for one request needs no sessions or streaming, and the SDK would add to a cold start that already dominates load time.
Hosting
- Chose
- A remote endpoint on the query API
- Instead of
- A local stdio server
- Why
- The stdio script needed a checkout of this private repo on every machine. A URL works from any app.
Tech stack
Languages
- Python
All four Lambdas, the operator scripts and the tests, strictly typed with mypy.
Frameworks
- FastAPI
The management API: metrics, comments, analyses, the action audit trail, the Instagram proxy, translations, post ideas and the media kit.
AI/ML
- Gemini
Structured-output analysis on Gemini Flash-Lite for comments and DM conversations, plus on-demand translations and post ideas.
Topics
- AWS Lambda
Four functions (webhook, processor, poller, query API), each packaged with only its own dependencies and precompiled bytecode, on arm64.
- API Gateway
Fronts the query API, rate-limited to 10 requests a second (bursts of 20) so a flood cannot take the Lambda concurrency the webhook needs.
- SQS
Decouples webhook ingestion from analysis, with a dead-letter queue, per-message batch failures and delayed retries when Gemini is overloaded.
- DynamoDB
Event metadata and idempotency claims, dense metric samples (90-day TTL), the due-gate the poller reads first, and single-use claims on OAuth codes.
- Aurora DSQL
Postgres-compatible storage for analyses, actions, one immutable row per day and the daily media kit, billed per request with nothing for idle time.
- S3
Raw webhook payloads and a daily bundle of raw Graph responses, kept because insights cannot be fetched again later.
- MCP
The media kit as one read-only tool over Streamable HTTP, written out by hand, with OAuth protected resource metadata so AI apps can sign in.
- Terraform
The whole stack, deployed from GitHub Actions through an OIDC role scoped to this project.
- pytest + moto
551 tests; the full webhook to SQS to processor to API path runs in-process against mocked AWS, and Postgres tests go through the production DSQL adapter.
Future improvements
- Liking comments. It needs
graph.facebook.comand Facebook Login for Business, which this account does not use, solikestays a suggestion. - Comment history before the webhook. Analyses only cover comments the webhook delivered. Older ones need the poller to own comments too.
- Per-story insights. Stories are about 1% of this account’s reach, and no story was live during two verification runs, so the metric set is still unverified.