Instagram API & MCP Server

What you can post

Instagram limits.

These are the limits the API enforces for Instagram, read straight from the code. Every post is checked against them before anything is sent.

Works with Instagram professional (Business or Creator) accounts. Every post needs an image or video; images must be JPEG.

Text: 2,200 characters
Images: Up to 10 per post · JPEG · 8 MB each
Video: Up to 10 per post · MP4, MOV · 60 MB
Images and video together: Allowed
Media: Required on every post
overrides.instagram.share_to_feed: boolean · Reels only (a post with one video): whether the reel can also appear in the main feed, not just the Reels tab. Instagram decides when omitted.

Post with one request

Your first Instagram post.

Send the text and the account ID. Add an Idempotency-Key so a retried request never posts twice. The response lists each account with its own status and, once it’s live, the post’s URL.

curl https://socialhelper.app/api/v1/posts \
  -H "Authorization: Bearer $SOCIALHELPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
      "text": "We just shipped dark mode. Try it tonight 🌙",
      "accounts": [
          "ACCOUNT_ID"
      ],
      "media": [
          "MEDIA_ID"
      ]
  }'

const response = await fetch("https://socialhelper.app/api/v1/posts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SOCIALHELPER_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
      "text": "We just shipped dark mode. Try it tonight 🌙",
      "accounts": [
          "ACCOUNT_ID"
      ],
      "media": [
          "MEDIA_ID"
      ]
  }),
});

const { data: post } = await response.json();
console.log(post.status, post.targets);

import os, uuid, requests

response = requests.post(
    "https://socialhelper.app/api/v1/posts",
    headers={
        "Authorization": f"Bearer {os.environ['SOCIALHELPER_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "text": "We just shipped dark mode. Try it tonight 🌙",
        "accounts": ["ACCOUNT_ID"],
        "media": ["MEDIA_ID"],
    },
)

post = response.json()["data"]
print(post["status"], post["targets"])

Tools

Instagram tools.

Call them with POST /api/v1/accounts/{id}/tools/{tool}, or let your agent use list_account_tools and run_account_tool over MCP. Results come back straight away.

list_media

read-only

List the account's most recent posts, reels and carousels, newest first (stories are not included), with caption, media type, publish time, permalink, and like and comment counts. Counts are null where the owner hid them.

limit integer: How many to return (1–50). default: 10
after string: The next_cursor from a previous call, to page back to older media.

account_insights

read-only

Account-level insights summed over a date range (default: the last 24 hours), optionally broken down. Data can lag up to 48 hours; reach and accounts_engaged are estimates; follows_and_unfollows needs 100+ followers.

metrics* array<string>: Metrics to fetch, one or more of: accounts_engaged, comments, follows_and_unfollows, likes, profile_links_taps, reach, replies, reposts, saves, shares, total_interactions, views.
metric_type string: "total_value" for one total per metric (all metrics), or "time_series" for daily values (reach only). total_value | time_series default: 'total_value'
breakdown string: Split totals (total_value only): media_product_type (comments, likes, reach, saves, shares, total_interactions, views), follow_type (follows_and_unfollows, reach, views) or contact_button_type (profile_links_taps). media_product_type | follow_type | contact_button_type
since string: First day, YYYY-MM-DD (UTC). Required with until; the range can span at most 30 days.
until string: Last day, YYYY-MM-DD (UTC, inclusive). Defaults to now when since is given.

media_insights

read-only

Lifetime insights for one post, reel or carousel (as list_media returns it). Metrics that do not apply to the media type are rejected by Instagram. Data can lag up to 48 hours.

media_id* string: The media ID from list_media.
metrics* array<string>: Metrics to fetch, one or more of: comments (feed posts and reels); crossposted_views (reels shared to Facebook); facebook_views (media shared to Facebook); follows (feed posts and stories); ig_reels_avg_watch_time (reels); ig_reels_video_view_total_time (reels); likes (feed posts and reels); navigation (stories); profile_activity (feed posts and stories); profile_visits (feed posts and stories); reach (all media); reels_skip_rate (reels); replies (stories); reposts (all media); saved (feed posts and reels); shares (all media); total_interactions (all media); views (all media).

Connect

Connect Instagram once.

Open Accounts in the SocialHelper dashboard and choose Instagram. You sign in on Instagram’s own screen and approve access; SocialHelper stores the connection encrypted. You don’t need a Instagram developer app of your own.

1

Open Accounts

In the dashboard, choose Instagram.
2

Sign in on Instagram

Approve access on Instagram’s own screen.
3

Use the account ID

GET /api/v1/accounts lists the account with its ID, whether it can publish, and its tools.