Build an Instagram Competitor Report Generator with Python

Most social media reporting workflows start the same way:

Someone opens a few competitor profiles, checks recent posts, copies links into a spreadsheet, guesses which Reels performed best, and turns everything into a weekly report.

That works once.

It becomes painful when you want to do it every week.

So I built a small open-source Python starter that turns public Instagram-style data into repeatable competitor intelligence reports.

The project is here:

https://github.com/prodkit-labs/instagram-competitor-intelligence

It is intentionally not an Instagram bot, not a login automation tool, and not an API wrapper.

It is a reporting workflow.

The goal is simple:

Take public profile and media data, rank what performed well, extract useful patterns, and generate a weekly competitor report.

What the project does

The current version can help you:

compare public competitor accounts
rank recent posts and Reels by engagement
extract hashtag trends from captions
detect creator, influencer, and brand mentions
export CSV-friendly metrics
generate weekly Markdown and HTML reports
run with mock data before connecting any real provider
schedule reports with GitHub Actions or cron

The most important design decision was this:

The project runs with mock data first.

That means you can try the full workflow without needing an API key, a provider account, or any production setup.

Why mock data first?

A lot of public-data projects fail at the first step because the user has to configure credentials before seeing any value.

I wanted the opposite.

You should be able to clone the repo, run one command, and immediately see the report structure.

Mock data is useful for:

understanding the workflow
testing the report generator
checking the metrics
reviewing the output format
deciding whether the project fits your use case

Only after that should you think about production data providers, scheduling, caching, cost control, and monitoring.

Quick Start

Clone the repo:

git clone https://github.com/prodkit-labs/instagram-competitor-intelligence.git
cd instagram-competitor-intelligence

Create a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Generate a sample weekly report with mock data:

python3 examples/06_generate_weekly_report.py --mock

The generated reports will be written to:

reports/sample_weekly_report.md
reports/sample_weekly_report.html

That is the fastest way to see the end-to-end workflow.

The basic workflow

The reporting pipeline looks like this:

public account data
        ↓
recent posts and Reels
        ↓
engagement metrics
        ↓
hashtag extraction
        ↓
creator / brand mention detection
        ↓
competitor comparison
        ↓
weekly Markdown / HTML report

The repo is organized around small examples instead of one large application.

For example:

examples/01_get_profile.py
examples/02_get_recent_media.py
examples/03_rank_top_reels.py
examples/04_extract_hashtags.py
examples/05_compare_competitors.py
examples/06_generate_weekly_report.py
examples/07_export_csv.py
examples/08_schedule_with_github_actions.md
examples/09_extract_creator_mentions.py
examples/10_estimate_api_cost.py

You can run the full report workflow, or just inspect one piece at a time.

Calculating engagement rate

For a simple competitor report, I usually start with a basic engagement rate:

engagement_rate = (like_count + comment_count) / follower_count

This is not perfect.

It does not account for reach, saves, shares, story views, or platform-specific ranking behavior.

But it is useful for comparing public posts across competitor accounts when you only have public-facing metrics.

For the first version of the project, I care more about a repeatable metric than a perfect metric.

A weekly report does not need to answer every question.

It needs to help you spot patterns.

What the report includes

The generated report includes sections like:

Weekly Instagram Competitor Report

1. Summary
2. Competitor activity
3. Top-performing posts and Reels
4. Hashtag trends
5. Creator and brand mentions
6. Practical recommendations
7. Raw CSV-friendly metrics

A report might answer questions like:

Which competitor posted the most this week?
Which Reels had the highest engagement rate?
Which hashtags appeared repeatedly?
Which creators or brands were mentioned?
Which content formats seem worth testing next?

This is the kind of information a social media analyst, indie brand, or agency might otherwise collect manually.

Production is a separate problem

Running the mock workflow is easy.

Running this in production is different.

Production workflows need answers to questions like:

Which public-data provider will you use?
How often will the report run?
How many competitor accounts will you monitor?
How many recent media items do you need per account?
What happens when a request fails?
How will you control API cost?
Where will reports be stored?
How will you monitor scheduled jobs?

That is why the repo separates the basic examples from the production docs.

The README is for trust and quick start.

The production docs are for provider decisions, deployment, observability, and cost control.

Cost control matters

A weekly competitor report can be cheap.

A daily report across many clients can get expensive quickly.

A rough estimate might look like this:

estimated_requests =
  competitors
  × endpoints_per_competitor
  × reports_per_month
  × retry_factor

For example:

10 competitors
2 endpoints per competitor
4 weekly reports per month
1.2 retry factor

10 × 2 × 4 × 1.2 = 96 estimated requests / month

For a small workflow, this is manageable.

For an agency monitoring many clients, this becomes a real production decision.

That is why the project includes cost-control notes instead of pretending provider choice does not matter.

What this project is not for

This project is only for public-data analysis and reporting.

It is not for:

collecting private account data
asking users for Instagram passwords
automating likes, follows, comments, or DMs
fake engagement
spam workflows
account automation
claiming official affiliation with Instagram, Meta, or any provider

I wanted the project to stay focused on reporting and analysis, not automation abuse.

Why I built it this way

The first version could have been a dashboard.

But I chose a small Python workflow instead.

A dashboard is useful once the data model is clear.

A report generator is useful immediately.

The current version is closer to a practical starter than a polished SaaS product:

clone
run mock workflow
inspect report
modify examples
decide if production setup is worth it

That felt like the right order.

Possible next steps

The project is still early, but the obvious next improvements are:

Streamlit dashboard demo
Google Sheets export guide
Notion report template
multi-client agency report template
more production deployment examples
better benchmark scripts
richer content theme classification

I am especially interested in the agency-reporting use case:

Add a few competitor accounts, run a weekly job, and generate a client-ready report automatically.

That is probably where this workflow becomes most useful.

Try it

Repo: