Instagram Lead Gen

Instagram RapidAPI Proxy — OfficeX App

Production is live and should always be used.

App ID (Production): 'b472aaf3-9b17-4d8c-b818-a6f8e2152eb5'

Single-vendor RapidAPI proxy wrapping 'instagram-social.p.rapidapi.com' as an OfficeX app. Serverless, AWS-native, scale-to-zero. See TEMPLATE_ARCHITECTURE.md for the full generic template this project implements.

Instagram API Reference

See .claude/skills/rapidapi-instagram/references/api_reference.md for full endpoint docs with parameters and response schemas.

Quick Reference

Authentication

''' Headers: X-RapidAPI-Key: {RAPID_API_KEY from .env} X-RapidAPI-Host: instagram-social.p.rapidapi.com

Base URL: https://instagram-social.p.rapidapi.com/api/v1/instagram Method: GET (all endpoints) '''

Response Format

'''json { "meta": { "version": "v1.0", "status": 200, "pagination_token": "..." | null }, "body": [ ... ] // array for list endpoints, object for /profile, /info } '''

Pagination: pass 'pagination_token' as query param for next page. 'null' = no more pages.

Direct Usage

'''javascript import 'dotenv/config'; const BASE = 'https://instagram-social.p.rapidapi.com/api/v1/instagram'; const headers = { 'x-rapidapi-key': process.env.RAPID_API_KEY, 'x-rapidapi-host': 'instagram-social.p.rapidapi.com' }; const res = await fetch('{BASE}/profile?username=mrbeast', { headers }); const data = await res.json(); // data.meta, data.body '''

REST API (This App's Endpoints)

Auth for all job/status endpoints: 'x-officex-install-id' + 'x-officex-install-secret' headers.

Submit Job

''' POST /api/v1/jobs

// Single (quick queue): { "endpoint": "profile", "params": { "username": "mrbeast" }, "prompt_filter": "optional AI filter" }

// Batch (bulk queue): { "endpoint": "posts", "params": [{ "username": "a" }, { "username": "b" }], "max_records": 100 }

// Response (202): { "job_id": "...", "status": "queued", "total_tasks": 1, "credits_reserved": 1.01, "poll_url": "/api/v1/jobs/..." } '''

Poll & Results

''' GET /api/v1/jobs/{job_id} — Job progress + cost breakdown GET /api/v1/jobs/{job_id}/results — Paginated results (preview + match_score + S3 URLs) GET /api/v1/jobs — List user's jobs PATCH /api/v1/jobs/{job_id} — Cancel: { "status": "cancelled" } '''

Result Items & Bookmarks

''' GET /api/v1/jobs/{job_id}/results/{task_index}/items/{item_index} PATCH /api/v1/jobs/{job_id}/results/{task_index}/items/{item_index} — { "user_bookmarked": true, "user_notes": "..." } GET /api/v1/jobs/{job_id}/result-rows — All bookmarks/notes for a job '''

Auth & Webhooks

''' POST /auth/register — { email, password } → { api_key, install_id } POST /auth/login — { email, password } → { api_key, install_id } POST /auth/officex-login — { officex_customer_id, install_id, install_secret } → { api_key } POST /webhooks/officex — INSTALL / UNINSTALL / RATE_LIMIT_CHANGE events POST /api/v1/webhooks/nocodb — NocoDB 2-way sync (bookmark/notes) GET / — Frontend HTML GET /docs — API documentation '''

Architecture

''' POST /api/v1/jobs → Ingress Lambda (validate + reserve credits + queue) ↓ ┌──────────┴──────────┐ Quick Queue (80%) Bulk Queue (20%) ↓ ↓ Quick Dispatcher Bulk Dispatcher └──────────┬──────────┘ Worker Lambda 1. Call Instagram API 2. Save to S3 (public URL, 90d) 3. Extract preview → DynamoDB 4. AI filter (Gemini) → match_score 5. Sip/Settle OfficeX credits 6. NocoDB sync (fire-and-forget) 7. Inbox notification on completion '''

Vendor Config

'''typescript // infrastructure/lib/vendors.config.ts { id: "instagram", rateLimitMax: 20, rateLimitWindowSecs: 5 } // 4 req/sec safe margin '''

Pricing

• Base: 1.01 credits/task (~$0.0101)
• With AI filter: 1.03 credits/task (~$0.0103)
• Billing: Reserve → Sip → Settle pattern (see '/officex-developer' skill)

Key Handlers

Key Libraries

DynamoDB Tables

S3

Bucket: 'rapi-ig-{stage}-results-{account}' — public read, 90-day lifecycle, CORS enabled. Objects: '{job_id}/{task_index}.json' (full response), '{job_id}/{task_index}/{item_index}.json' (individual items).

NocoDB Results Tables

Preview Extractor Fields (by endpoint)

• profile: username, full_name, is_verified, is_private, is_business, biography, followers, following, posts, category, external_url
• posts/info: shortcode, media_type, product_type, caption, like_count, comment_count, play_count, permalink, taken_at
• followers/following: result_count, username, full_name, is_verified, is_private
• comments: result_count, text, username
• likes: result_count, username, full_name, is_verified
• highlights: result_count, title, media_count
• users-search: result_count, username, full_name, is_verified, is_private
• hashtags-search: result_count, name, media_count

Infrastructure (CDK)

''' infrastructure/bin/app.ts — CDK app entry infrastructure/lib/rapi-stack.ts — Main stack (all resources) infrastructure/lib/app.config.ts — PROJECT_TAG = "rapidapi-proxy" infrastructure/lib/vendors.config.ts — Single vendor: instagram '''

Deploy

'''bash

Production (default — always use production)

npm run deploy:prod

Register OfficeX app (production)

STAGE=production API_URL=https://instagram-lead-gen-production.cloud.zoomgtm.com npm run register:prod

Staging (for development only)

npm run deploy:staging npm run register:staging '''

Resources Created

4 Lambdas (ingress 256MB/30s, worker 512MB/60s, status 256MB/30s, 2× dispatcher 128MB/30s), 4 SQS FIFO queues + 4 DLQs, 5 DynamoDB tables, 1 S3 bucket, 1 CloudFront distribution, 1 HTTP API Gateway.

All tagged: 'app=rapi-ig-{stage}', 'project=rapidapi-proxy', 'vendor=instagram'.

Environment Variables

'''env

Required

RAPID_API_KEY= # RapidAPI key for instagram-social GEMINI_API_KEY= # Gemini AI filter AWS_ACCESS_KEY_ID= # AWS auth (use .env, not aws cli) AWS_SECRET_ACCESS_KEY= AWS_REGION=

OfficeX

OFFICEX_USER_ID= # For app registration OFFICEX_API_KEY= # For app registration

NocoDB (optional — graceful degradation if missing)

NOCODBHOST_URL= NOCODB_TOKEN= NOCODB_BASE= NOCODB_TABLE_INSTALLS= NOCODB_TABLE_JOBS= NOCODB_TABLE_RESULTS_PROFILES= NOCODB_TABLE_RESULTS_POSTS= NOCODB_TABLE_RESULTS_USERS= NOCODB_TABLE_RESULTS_COMMENTS= NOCODB_FIELD*= # Link field IDs for views/filters NOCODB_WEBHOOK_SECRET= '''

Auto-Pagination

Paginated endpoints (followers, following, posts, comments, likes) auto-follow cursors. User sets 'max_records' (default 100, max 1000). Worker queues follow-up tasks with incremented 'task_index' via atomic 'incrementTotalTasks()'. Credits reserved upfront for estimated total; final settle refunds unused.

Job Lifecycle

'queued → processing → completed | failed | cancelled'

Also supports: 'processing → paused → processing (resume)'. Dispatcher and worker check status; paused tasks requeue with 60s delay.

Error Handling

• Rate limit (429): Progressive backoff requeue (30s → 12h), new dedup ID per retry
• Real errors: SQS natural retry (3 attempts), then DLQ (14-day retention)
• Billing errors during sip/settle: Logged, not fatal — result already saved
• NocoDB errors: Fire-and-forget, logged silently — AWS is source of truth