Instagram API reference

Quickstart

Create a key in your dashboard, then fetch a profile:

curl "https://api.instagramapi.dev/v1/profile?handle=nike" \
  -H "Authorization: Bearer $INSTAGRAMAPI_KEY"

const res = await fetch("https://api.instagramapi.dev/v1/profile?handle=nike", {
  headers: { Authorization: `Bearer ${process.env.INSTAGRAMAPI_KEY}` },
});

res = requests.get("https://api.instagramapi.dev/v1/profile?handle=nike",
    headers={"Authorization": f"Bearer {INSTAGRAMAPI_KEY}"})

Prefer to generate a client or wire this into an AI agent? Grab the OpenAPI spec (https://api.instagramapi.dev/openapi.json). It works with Swagger/Redoc, Postman, SDK generators, and agent tool loaders like ChatGPT Actions and LangChain.

Authentication

Pass your secret key as a bearer token on every request. You can also use the x-api-key header. Keys are created and revoked from the dashboard and are shown in full only once.

Authorization: Bearer ig_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

MCP server

Every endpoint is also exposed as an MCP tool, so AI assistants (Claude Code, Claude Desktop, Cursor, agent frameworks) can call the API conversationally. The server speaks Streamable HTTP at:

https://api.instagramapi.dev/mcp

Authenticate with the same bearer API key as the REST API. Tool names mirror endpoint paths with underscores (profile/posts → profile_posts), inputs match the documented query params, and results are the same JSON envelope — billed identically, with meta.credits_remaining in every result.

claude mcp add --transport http instagram https://api.instagramapi.dev/mcp \
  --header "Authorization: Bearer ig_live_YOUR_KEY"

// .cursor/mcp.json
{
  "mcpServers": {
    "instagram": {
      "url": "https://api.instagramapi.dev/mcp",
      "headers": { "Authorization": "Bearer ig_live_YOUR_KEY" }
    }
  }
}

// Settings (⌘,) → Developer → Edit Config opens claude_desktop_config.json.
// Add this, save, then fully restart Claude Desktop (needs Node.js for npx):
{
  "mcpServers": {
    "instagram": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://api.instagramapi.dev/mcp",
        "--header", "Authorization: Bearer ig_live_YOUR_KEY"
      ]
    }
  }
}

# Debug the server + try tools in a UI
npx @modelcontextprotocol/inspector
# → transport: "Streamable HTTP", URL: https://api.instagramapi.dev/mcp
# → header:    Authorization: Bearer ig_live_YOUR_KEY

Tool-call failures come back as structured errors with the same code values as REST (see Errors), so agents can recover — top up on insufficient_credits, fix input on missing_parameter. Clients that can't send custom headers (e.g. claude.ai web custom connectors, which require OAuth) aren't supported yet. More on the MCP overview page.

Responses

Every successful response uses the same envelope: your payload under data, plus a meta object with billing info. A single resource (like a profile or post) comes back as a flat object:

{
  "data": {
    "id": "13460080",
    "username": "nike",
    "full_name": "Nike",
    "followers": 291952375
    // …
  },
  "meta": {
    "endpoint": "profile",
    "request_id": "req_8f3c1a2b",
    "credits_charged": 1,
    "credits_remaining": 4987,
    "ms": 412
  }
}

List endpoints (posts, followers, comments, search, …) wrap results in items with a next_cursor:

{
  "data": {
    "items": [ /* … */ ],
    "next_cursor": "QVFE..."
  },
  "meta": { "endpoint": "profile/followers", "credits_charged": 2, "credits_remaining": 4985, "ms": 530 }
}

To page, pass next_cursor back as the cursor query parameter; a null cursor means the last page. Billing also comes back as x-credits-remaining and x-request-id response headers.

Billing

Credits are charged per request. Most endpoints cost 1 credit.Endpoints that must first resolve an account or post to fetch a sub-resource, like followers, a profile's posts, or a post's comments, cost 2 credits. The exact cost is shown on every endpoint's reference page and returned as meta.credits_charged.

The rule for whether you're charged is simple: if your request is well-formed and we query Instagram for you, it's billed, even when the answer is “no public data here.” A lookup for a private, deleted, or nonexistent account is a real query on our side, so it bills (and returns 404). What you are never charged for: input we reject before querying (a missing or malformed parameter), authentication problems, an empty balance, or a provider/network error on our side.

Errors

Errors return a matching HTTP status and a typed body. The Billed? column below follows the rule above: your input errors and our outages are free; a well-formed request that reaches Instagram is billed even if no data comes back.

Pagination

List endpoints return meta.next_cursor. Pass it back as the cursor query param to get the next page. When next_cursor is null, you've reached the end.