Instagram API
The Instagram API requires weeks of Meta app review, complex OAuth flows, 60-day token rotation, and 3 API calls just to post a carousel. Aether wraps all of that into one endpoint — so you post photos, carousels, and Reels in the same call, with one API key.
One call for photos, carousels, and scheduled posts. Aether handles media containers, format validation, and retry logic.
import Aether from "aether";
const aether = new Aether({ apiKey: process.env.AETHER_API_KEY });
// Single photo post
const photo = await aether.posts.create({
text: "Shipping something new today 🚀 #buildinpublic",
profileIds: ["ig_abc123"],
mediaUrls: ["https://your-cdn.com/photo.jpg"],
});
// Carousel post (up to 10 images)
const carousel = await aether.posts.create({
text: "A thread of behind-the-scenes shots 📷",
profileIds: ["ig_abc123"],
mediaUrls: [
"https://your-cdn.com/slide-1.jpg",
"https://your-cdn.com/slide-2.jpg",
"https://your-cdn.com/slide-3.jpg",
],
});
// Scheduled post
const scheduled = await aether.posts.create({
text: "See you tomorrow morning ☀️",
profileIds: ["ig_abc123"],
mediaUrls: ["https://your-cdn.com/morning.jpg"],
scheduledFor: "2026-06-15T09:00:00Z",
});Free tier · 3 accounts · no credit card
Get your free API keyimport os
import aether
client = aether.Aether(api_key=os.environ["AETHER_API_KEY"])
# Single photo post
post = client.posts.create(
text="Shipping something new today 🚀 #buildinpublic",
profile_ids=["ig_abc123"],
media_urls=["https://your-cdn.com/photo.jpg"],
)
# Scheduled carousel
carousel = client.posts.create(
text="A thread of behind-the-scenes shots 📷",
profile_ids=["ig_abc123"],
media_urls=["https://your-cdn.com/slide-1.jpg", "https://your-cdn.com/slide-2.jpg"],
scheduled_for="2026-06-15T09:00:00Z",
)curl -X POST https://api.aetherhq.dev/v1/posts \
-H "Authorization: Bearer $AETHER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Shipping something new today 🚀 #buildinpublic",
"profileIds": ["ig_abc123"],
"mediaUrls": ["https://your-cdn.com/photo.jpg"],
"scheduledFor": "2026-06-15T09:00:00Z"
}'Aether returns a normalized post object immediately. Once published, the publishResults array includes the platform-native Instagram post ID and publish timestamp.
{
"success": true,
"data": {
"id": "post_2k4mn8x",
"status": "scheduled",
"text": "Shipping something new today 🚀 #buildinpublic",
"profileIds": ["ig_abc123"],
"mediaUrls": ["https://cdn.aetherhq.dev/org_9p2qrs/photo.jpg"],
"mediaKeys": ["org_9p2qrs/photo.jpg"],
"scheduledFor": "2026-06-15T09:00:00.000Z",
"publishResults": [],
"publishedAt": null,
"failedAt": null,
"createdAt": "2026-06-08T14:23:11.000Z"
}
}Getting instagram_content_publish directly means: register a Meta developer app, record a screen-share video of the OAuth flow, submit for review, wait weeks for approval, then build token refresh infrastructure for the 60-day expiry.
Aether's Connect Link removes all of that. Call one endpoint, get a URL, send it to your user. They click, Instagram authenticates them, and their account appears in your dashboard.
// Generate a Connect Link for your user to authenticate Instagram
const link = await aether.connectLinks.create({
platform: "instagram",
redirectUrl: "https://yourapp.com/settings/social",
});
// Send link.url to your user — they click, authenticate on Instagram,
// and the account appears in your dashboard automatically.
// No Meta app setup needed on your end.
console.log(link.url); // "https://connect.aetherhq.dev/link/cl_xk9p2m..."
console.log(link.expiresAt); // "2026-06-15T14:23:11.000Z"Aether's Connect Link handles Instagram OAuth on your behalf. Your users connect in one click — no Meta developer portal work on your side.
Single images, multi-image carousels (up to 10), and Stories. Aether handles the multi-step container API — you send one request.
Upload videos directly or pass a URL. Aether handles format validation, container creation, and processing wait — then publishes automatically.
Pass scheduledFor in your request. Aether queues the post and publishes at the right time. Supports timezone strings for account-local scheduling.
Read and reply to Instagram comments and DMs programmatically. All threads in one unified inbox API surface across platforms.
Impressions, reach, likes, saves, comments — per post and per account. Historical data with custom date ranges and sub-second queries.
Historical engagement analysis per account tells you the optimal days and hours to publish for maximum reach.
Every Instagram endpoint is an MCP tool. Claude, Cursor, and any MCP-compatible agent can post, schedule, and retrieve analytics.
Impressions, reach, likes, saves, and follower delta — post-level and account-level, over any date range, with sub-second Tinybird queries.
// Post-level analytics
const metrics = await aether.analytics.getPostMetrics("post_2k4mn8x");
// [{ metricType: "impression", value: 2840 }, { metricType: "like", value: 127 }, ...]
// Account analytics for June
const account = await aether.analytics.getAccountMetrics({
profileId: "ig_abc123",
from: "2026-06-01",
to: "2026-06-30",
granularity: "day",
});
// Best times to post on this Instagram account
const bestTimes = await aether.analytics.getBestPostingTimes({
platform: "instagram",
});You can — but you take on everything Meta requires. Here's the realistic comparison.
| Feature | Aether | Instagram Graph API directly |
|---|---|---|
| Authentication | ✓One API key | ✗App Review + complex OAuth 2.0 |
| Rate limits | ✓Automatic retry & backoff | ✗Manually managed per endpoint |
| Media hosting | ✓Upload to Aether, we handle the rest | ✗External CDN required |
| API maintenance | ✓We absorb all breaking changes | ✗Your team's responsibility |
| Time to first post | ✓< 15 minutes | ✗Days to weeks |
| Platform compliance | Official API, fully compliant | Official API, fully compliant |
Platform-level limits set by Instagram. Aether queues and retries automatically — your integration does not need backoff logic.
| Operation | Limit | Error code | Note |
|---|---|---|---|
| Content publish | 50 posts / 24 h | 341 | Per Instagram account |
| API calls | 200 calls / hr / token | 17 | Per access token |
| Media file size | 100 MB per file | 352 | Images + videos |
| Video (Feed) | 60 s max · min 3 s | — | MP4 / MOV |
| Reels | 90 min max · 50 / day | — | Per account |
| Carousel | 10 items max | 100 | Images or videos |
| Caption | 2,200 characters | 100 | UTF-8, links not clickable |
| Hashtags | 30 per post | 100 | Instagram limit |
| Code | Meaning | How Aether handles it |
|---|---|---|
| 190 | Invalid or expired OAuth token | Aether auto-refreshes — reconnect if it persists |
| 200 | Missing permission scope | Re-connect via Connect Link; all scopes are requested upfront |
| 341 | Daily publish limit (50/day) reached | Aether queues and retries after the window resets |
| 368 | Account temporarily blocked | Content policy issue — review the post before resubmitting |
| 10 | App review gate — permission denied | Use Aether — Meta review is Aether's problem, not yours |
| 100 | Invalid request parameter | Aether validates the request; check your input |
| 352 | Media file too large | Compress below 100 MB — Aether will surface this before sending |
AI-Native
Aether ships an MCP server that exposes every Instagram endpoint as a callable tool. Claude Desktop, Cursor, Windsurf, and any MCP-compatible agent can post, schedule, pull analytics, and manage DMs — with no additional integration code.
# Add to ~/.claude/claude_desktop_config.json
{
"mcpServers": {
"aether": {
"command": "npx",
"args": ["-y", "aether-mcp"],
"env": { "AETHER_API_KEY": "sk_live_..." }
}
}
}
# Claude can now post to Instagram, pull analytics, and manage DMs:
# "Post our launch photo to Instagram now"
# "Schedule tomorrow's carousel for 9am"
# "What's our Instagram engagement rate this week?"With Aether you call POST /v1/posts with your Instagram profile ID and content. Aether handles all underlying Graph API calls — media containers, carousel assembly, processing waits, and scheduling — so you send one request and get back one normalized response.
No. Aether's platform app has already completed Meta's review and holds the instagram_content_publish permission. Your app only needs an Aether API key. No Meta developer portal setup, no screen-share video, no waiting.
Instagram allows 50 published posts per 24 hours per account and 200 API calls per hour per access token. Aether automatically queues and retries requests that hit platform rate limits, surfacing the status in the post's publishResults field.
Yes. Pass scheduledFor as an ISO 8601 datetime string. Aether stores the post as 'scheduled' and publishes it at the correct time. You can also pass a timezone string to schedule in the account's local time zone.
With Aether you just pass multiple URLs in mediaUrls — up to 10 items. Aether handles the multi-step Graph API carousel flow (create per-item containers, create carousel container, publish) automatically. No extra code on your end.
Free tier · 3 accounts · full API access · MCP server · no credit card.
Get your free API key →