Instagram API documentationمستندات Instagram API

The :username is not a plain Instagram username: only letters, digits, . and _, at most 30 characters — no @, no link.:username یک نام کاربری سادهٔ اینستاگرام نیست: فقط حروف، عدد، . و _، حداکثر ۳۰ نویسه — بدون @ و بدون لینک.

What to do: strip the @ or take the name out of the profile link; do not retry the same value.@ را بردارید یا نام را از لینک پروفایل جدا کنید؛ همان مقدار را تکرار نکنید.

{ "error": "invalid_username", "message": "Invalid username. Please enter a plain Instagram username (e.g. instagram), not a URL or link." }

A parameter is missing or malformed: /api/media without url / shortcode / id or with a link that holds no post id; a highlight id that is not 5–25 digits; a max_id with characters a cursor never has. Also sent when Instagram itself rejects the input.پارامتری غایب یا نامعتبر است: /api/media بدون url / shortcode / id یا با لینکی که شناسهٔ پست ندارد؛ شناسهٔ هایلایتی که ۵ تا ۲۵ رقم نیست؛ max_id با نویسه‌هایی که یک cursor ندارد. وقتی خود اینستاگرام ورودی را رد کند هم همین می‌آید.

What to do: fix the parameter (pass nextMaxId exactly as you got it); do not retry unchanged.پارامتر را اصلاح کنید (nextMaxId را دقیقاً همان‌طور که گرفتید بفرستید)؛ بدون تغییر تکرار نکنید.

{ "error": "invalid_input", "message": "Provide a post ?url= (or ?id= / ?shortcode=)" }

The URL could not be decoded, for example a broken percent-escape in the path.آدرس قابل decode نیست، مثلاً یک percent-escape ناقص در مسیر.

What to do: URL-encode path and query values once (encodeURIComponent, urlencode).مقدارهای مسیر و query را یک بار URL-encode کنید.

{ "error": "bad_request", "message": "Failed to decode param '%E0%A4%A'" }

The request had a JSON body that could not be parsed. Every public endpoint is GET and needs no body.درخواست یک بدنهٔ JSON خراب داشت. همهٔ سرویس‌های عمومی GET هستند و بدنه لازم ندارند.

What to do: send no body and no Content-Type: application/json.بدنه و هدر Content-Type: application/json نفرستید.

{ "error": "invalid_json", "message": "Request body is not valid JSON" }

A request body over 1 MB. As above, the public endpoints take no body.بدنهٔ درخواست بیش از ۱ مگابایت. مثل بالا، سرویس‌های عمومی بدنه نمی‌گیرند.

What to do: send no body.بدنه نفرستید.

{ "error": "payload_too_large", "message": "Request body is too large" }

Sent only when this server requires a key (see Authentication) and the request has no X-API-Key header. The answer carries WWW-Authenticate: ApiKey realm="IGAPI" and is never cached.فقط وقتی فرستاده می‌شود که این سرور کلید را لازم کرده (بخش احراز هویت) و درخواست هدر X-API-Key ندارد. پاسخ هدر WWW-Authenticate: ApiKey realm="IGAPI" دارد و هرگز کش نمی‌شود.

What to do: send your key in the X-API-Key header; how to get one: Getting a key.کلیدتان را در هدر X-API-Key بفرستید؛ گرفتن کلید: گرفتن کلید.

{
  "error": "api_key_required",
  "message": "This API needs a key: send it in the X-API-Key header. How to get one: https://igapi.online/pricing",
  "apiKeyStatus": "missing",
  "docs": "https://igapi.online/docs#auth"
}

Sent only when this server requires a key and the X-API-Key you sent is unknown or revoked; the answer also has the header X-API-Key-Status: invalid. Under the other settings such a key is handled like a request without a key.فقط وقتی فرستاده می‌شود که این سرور کلید را لازم کرده و X-API-Key ارسالی ناشناخته یا باطل‌شده است؛ پاسخ هدر X-API-Key-Status: invalid را هم دارد. در تنظیم‌های دیگر با چنین کلیدی مثل درخواستِ بدون کلید رفتار می‌شود.

What to do: check the key (GET /api/health with it shows "apiKey": "invalid" without spending a request), or ask us for a new one.کلید را بررسی کنید (GET /api/health با همان کلید بدون مصرف درخواست "apiKey": "invalid" نشان می‌دهد) یا از ما کلید تازه بخواهید.

{
  "error": "api_key_invalid",
  "message": "The X-API-Key you sent is not recognised on this server (unknown or revoked). Check the key or ask for a new one: https://igapi.online/pricing",
  "apiKeyStatus": "invalid",
  "docs": "https://igapi.online/docs#auth"
}

The key runs on pay-as-you-go credits (created that way in the portal) and the account's credits are used up or expired. The request is not served and nothing is counted; topup_url is the portal's credits page. A key on a monthly plan never gets this answer.کلید روی اعتبارِ پرداخت‌به‌مصرف است (در پورتال این‌طور ساخته شده) و اعتبار حساب تمام یا منقضی شده است. درخواست انجام نمی‌شود و چیزی شمرده نمی‌شود؛ topup_url صفحهٔ اعتبار پورتال است. کلیدِ پلن ماهانه هرگز این پاسخ را نمی‌گیرد.

What to do: add credits in the portal (they are usable within seconds), then send the same request again.در پورتال اعتبار بخرید (ظرف چند ثانیه قابل استفاده است) و همان درخواست را دوباره بفرستید.

{
  "error": "no_credits",
  "message": "This API key runs on credits and the account has none left. Add credits at https://igapi.online/portal/credits to keep going.",
  "topup_url": "https://igapi.online/portal/credits",
  "balance": 0
}

The key's free period has ended: a Free key works for 10 days (one free key per account, 1,000 requests). A key made for a plan purchase answers the same until the payment confirms. Nothing is counted; buy_url is the key's page in the portal.دورهٔ رایگان کلید تمام شده است: کلید Free ده روز کار می‌کند (یک کلید رایگان برای هر حساب، ۱٬۰۰۰ درخواست). کلیدی که برای خرید پلن ساخته شده هم تا تأیید پرداخت همین پاسخ را می‌دهد. چیزی شمرده نمی‌شود؛ buy_url صفحهٔ کلید در پورتال است.

What to do: buy a plan for this key in the portal — the key string stays the same — then send the request again.در پورتال برای همین کلید پلن بخرید — رشتهٔ کلید عوض نمی‌شود — و درخواست را دوباره بفرستید.

{
  "error": "plan_expired",
  "message": "The Free period of this API key ended on 2026-11-17 (UTC). Buy a plan for this key at https://igapi.online/portal/keys/k_3f9a0c1d2e4b5a6f to keep using it — the key string stays the same.",
  "plan_id": "trial",
  "ended_at": "2026-11-17T10:00:00.000Z",
  "buy_url": "https://igapi.online/portal/keys/k_3f9a0c1d2e4b5a6f"
}

The portal account this key belongs to has been disabled by support. Every key of the account answers this until the account is enabled again; nothing is counted and the key, its plan and your credits stay as they are.حساب پورتالی که این کلید به آن تعلق دارد از طرف پشتیبانی غیرفعال شده است. همهٔ کلیدهای آن حساب تا فعال‌شدن دوباره همین پاسخ را می‌دهند؛ چیزی شمرده نمی‌شود و کلید، پلن و اعتبار شما دست نمی‌خورند.

What to do: do not retry; contact support (the e-mail on the portal sign-in page) to have the account enabled.تکرار نکنید؛ برای فعال‌شدن حساب با پشتیبانی تماس بگیرید (ایمیل روی صفحهٔ ورود پورتال).

{
  "error": "customer_disabled",
  "message": "The account this API key belongs to is disabled. Contact support to have it enabled again."
}

The profile is private. /api/feed always refuses a private profile; stories and highlights are refused unless one of the server's accounts follows it; /api/media and /api/highlight/:id refuse only when strict privacy is turned on. user (when present) has the public part of the profile, so you can still show a card.پیج خصوصی است. /api/feed همیشه پیج خصوصی را رد می‌کند؛ استوری و هایلایت رد می‌شوند مگر یکی از اکانت‌های سرور آن را فالو کند؛ /api/media و /api/highlight/:id فقط وقتی حالت سخت‌گیرانه روشن باشد. user (اگر باشد) بخش عمومی پروفایل را دارد تا هنوز بتوانید کارت پروفایل را نشان دهید.

What to do: do not retry; show that the account is private.تکرار نکنید؛ نشان دهید که اکانت خصوصی است.

{
  "error": "private_account",
  "message": "This account is private",
  "isPrivate": true,
  "user": { "pk": "1440211", "username": "some.private.user", "fullName": "Some User", "isPrivate": true, "profilePic": "https://scontent.cdninstagram.com/v/t51.2885-19/p.jpg" }
}

No such user, post or highlight on Instagram — or no such endpoint on this server (No such endpoint: GET /api/…).چنین کاربر، پست یا هایلایتی در اینستاگرام نیست — یا چنین سرویسی روی این سرور نیست (No such endpoint: GET /api/…).

What to do: check the spelling or the link; a renamed account answers 404 under its old name.املای نام یا لینک را بررسی کنید؛ اکانتی که نامش عوض شده با نام قدیم 404 می‌دهد.

{ "error": "not_found", "message": "User not found: ghost.user.123" }

Your key used up its plan in one window (window: minute, day or month, UTC). resetAt is when that window ends; Retry-After / retryAfterMs is how long to wait.کلید شما سهمیهٔ پلنش را در یک بازه مصرف کرده (window: minute، day یا month، به وقت UTC). resetAt زمان پایان آن بازه است و Retry-After / retryAfterMs مدت انتظار.

What to do: wait until resetAt (retrying earlier is refused again but not counted), or ask us for a bigger plan.تا resetAt صبر کنید (تکرار زودتر دوباره رد می‌شود ولی شمرده نمی‌شود)، یا از ما پلن بزرگ‌تر بخواهید.

{
  "error": "plan_limit_exceeded",
  "plan": "starter",
  "window": "minute",
  "limit": 30,
  "current": 30,
  "retryAfterMs": 21000,
  "resetAt": "2026-11-01T09:15:00.000Z",
  "message": "This API key's plan \"Starter\" allows 30 requests per minute, and this key has used 30. Try again in 21 s (resets at 2026-11-01T09:15:00.000Z), or ask for a bigger plan."
}

Too many requests from your IP without a valid key. The data endpoints have this limit only when it is turned on; /api/download allows 30 and /api/proxy-image 600 keyless requests a minute by default, each a separate budget. "apiKeyStatus": "invalid" means you did send a key but the server does not know it (unknown or revoked). When this server gives requests without a key the trial plan's limits, the body also has window (minute or day), resetAt and "plan": "trial".درخواستِ بدون کلیدِ معتبرِ زیاد از IP شما. سرویس‌های داده این سقف را فقط وقتی دارند که روشن شده باشد؛ /api/download به‌طور پیش‌فرض ۳۰ و /api/proxy-image ۶۰۰ درخواست بدون کلید در دقیقه، هر کدام سهمیهٔ جدا. "apiKeyStatus": "invalid" یعنی کلید فرستاده‌اید ولی سرور آن را نمی‌شناسد (ناشناخته یا باطل‌شده). وقتی این سرور به درخواست‌های بدون کلید سقف‌های پلن trial را می‌دهد، بدنه window (minute یا day)، resetAt و "plan": "trial" را هم دارد.

What to do: wait Retry-After, or send a valid X-API-Key (a valid key lifts this limit).به اندازهٔ Retry-After صبر کنید یا یک X-API-Key معتبر بفرستید (کلید معتبر این سقف را برمی‌دارد).

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests: the X-API-Key you sent is not recognised on this server (unknown or revoked), so this request was treated as one without a key — at most 60 per minute per IP. Check the key or ask for a new one.",
  "limit": 60,
  "current": 60,
  "retryAfterMs": 38400,
  "apiKeyStatus": "invalid"
}

Instagram is rate-limiting the account that served the request — not your key. Retry-After: 60. Not charged: the request is given back to your key.اینستاگرام اکانتی را که درخواست را انجام داد محدود کرده — نه کلید شما را. Retry-After: 60. هزینه‌ای ندارد: درخواست به کلید شما برگردانده می‌شود.

What to do: wait a minute and retry; another account usually serves it.یک دقیقه صبر کنید و دوباره بفرستید؛ معمولاً اکانت دیگری جواب می‌دهد.

{ "error": "rate_limited", "message": "Instagram is rate-limiting the service — retry in a minute.", "retryAfterMs": 60000 }

The request failed on the server or on the way to Instagram (an error it could not classify). When the cause was a network failure (proxy, timeout, an Instagram 5xx) the request is given back to your key.درخواست روی سرور یا در مسیر اینستاگرام شکست خورد (خطایی که دسته‌بندی نشد). اگر علتش خطای شبکه بود (پراکسی، timeout، خطای 5xx اینستاگرام) درخواست به کلید شما برگردانده می‌شود.

What to do: retry with exponential backoff, at most three times; tell us if it persists.با backoff نمایی، حداکثر سه بار، دوباره بفرستید؛ اگر ادامه داشت به ما بگویید.

{ "error": "server_error", "message": "The request failed on the server — please retry." }

The profile was read but Instagram's story request failed — an empty list would wrongly mean "no stories". Not charged: the request is given back to your key.پروفایل خوانده شد ولی درخواست استوری اینستاگرام شکست خورد — لیست خالی به اشتباه یعنی «استوری ندارد». هزینه‌ای ندارد: درخواست به کلید شما برگردانده می‌شود.

What to do: retry with backoff.با backoff دوباره بفرستید.

{ "error": "upstream_failed", "message": "Stories unavailable right now, retry" }

The server's Instagram account that took the request just failed and was taken out of rotation; reason says why: challenge_required, session_expired, session_limited or ip_blocked. It is never about your key or your input, and it is not charged: the request is given back to your key. Retry-After is 30 s (60 s for session_limited and ip_blocked).اکانتِ اینستاگرامِ سرور که درخواست را گرفت همین الان خطا داد و از چرخه کنار رفت؛ reason دلیلش را می‌گوید: challenge_required، session_expired، session_limited یا ip_blocked. هیچ‌وقت به کلید یا ورودی شما ربطی ندارد و هزینه‌ای ندارد: درخواست به کلید شما برگردانده می‌شود. Retry-After سی ثانیه است (برای session_limited و ip_blocked شصت ثانیه).

What to do: wait Retry-After and send the same request again — another account serves it.به اندازهٔ Retry-After صبر کنید و همان درخواست را دوباره بفرستید — اکانت دیگری جواب می‌دهد.

{
  "error": "session_unavailable",
  "reason": "challenge_required",
  "message": "The account serving this request is temporarily unavailable — please retry shortly.",
  "retryAfterMs": 30000
}

No Instagram account of the server is available right now (all challenged, disabled or at their own limit). There is no Retry-After; GET /api/health shows "status": "no_sessions" while this lasts. It costs your key nothing: the request is given back to its plan.فعلاً هیچ اکانت اینستاگرامی از سرور در دسترس نیست (همه challenge خورده، غیرفعال یا به سقف خودشان رسیده‌اند). Retry-After ندارد؛ تا وقتی این وضع هست، GET /api/health مقدار "status": "no_sessions" را نشان می‌دهد. از کلید شما چیزی کم نمی‌شود: درخواست به پلن آن برگردانده می‌شود.

What to do: retry later with exponential backoff (30 s, 60 s, 120 s …).بعداً با backoff نمایی (۳۰، ۶۰، ۱۲۰ ثانیه …) دوباره بفرستید.

{ "error": "no_sessions", "message": "No active sessions available" }

Only the lookup tools on this website get this answer — never a request from your own code. It means all visitors of the tools together reached the per-minute limit this server sets for them (only when requests without a key are limited or need a key). Retry-After gives the wait in seconds.فقط ابزارهای جست‌وجوی همین سایت این پاسخ را می‌گیرند — هرگز درخواستی از کد خودتان. یعنی همهٔ بازدیدکنندگان ابزارها روی‌هم به سقف دقیقه‌ای که این سرور برایشان گذاشته رسیده‌اند (فقط وقتی درخواستِ بدون کلید محدود است یا کلید لازم دارد). Retry-After زمان انتظار را برحسب ثانیه می‌گوید.

What to do: wait Retry-After and try again.به اندازهٔ Retry-After صبر کنید و دوباره امتحان کنید.

{ "error": "site_busy", "message": "The lookup tools are busy right now. Try again in a moment.", "retryAfterMs": 12000 }

No url, not https, not an Instagram CDN host (*.cdninstagram.com, *.fbcdn.net), or (download) a port or user name in it.url نیست، https نیست، میزبانش CDN اینستاگرام (*.cdninstagram.com، *.fbcdn.net) نیست، یا (در دانلود) پورت یا نام کاربری دارد.

What to do: pass a media URL from one of the data endpoints, URL-encoded.آدرس مدیایی را که یکی از سرویس‌های داده داده، URL-encode شده بفرستید.

{ "error": "Invalid URL" }

The image is over 8 MB.تصویر بیش از ۸ مگابایت است.

What to do: use a smaller candidate from images, or /api/download.نسخهٔ کوچک‌تری از images را بگیرید، یا /api/download.

{ "error": "Image too large" }

The file is bigger than the server's download cap (500 MB by default). A file without a declared size that grows past it is cut off mid-stream instead.فایل از سقف دانلود سرور (پیش‌فرض ۵۰۰ مگابایت) بزرگ‌تر است. فایلی که حجمش اعلام نشده و از سقف بگذرد، وسط کار قطع می‌شود.

What to do: pick a lower-resolution entry from videos.نسخهٔ با کیفیت پایین‌تر را از videos بگیرید.

{ "error": "File too large" }

The URL answered something that is not an image (for example a video).آدرس چیزی جز تصویر برگرداند (مثلاً ویدیو).

What to do: use thumbnailUrl for pictures and /api/download for videos.برای تصویر thumbnailUrl و برای ویدیو /api/download را استفاده کنید.

{ "error": "Not an image" }

The URL answered neither an image nor a video.آدرس نه تصویر برگرداند نه ویدیو.

What to do: pass a mediaUrl / images / videos URL.یک آدرس mediaUrl / images / videos بدهید.

{ "error": "Not an image or video" }

The CDN did not answer in time (15 s for the headers) or the connection failed. /api/proxy-image passes other CDN errors (403, 404, 410 …) through with the CDN's status and an empty body — CDN links expire after a while. /api/download also answers 502 Proxy error when the CDN itself answered an error other than 403 / 404 / 410 (for example its own 429 or a 5xx); then the body has upstreamStatus and a message, and there is no Retry-After.CDN به‌موقع جواب نداد (۱۵ ثانیه برای هدرها) یا اتصال قطع شد. /api/proxy-image خطاهای دیگر CDN (403، 404، 410 …) را با همان کد CDN و بدنهٔ خالی عبور می‌دهد — لینک‌های CDN بعد از مدتی منقضی می‌شوند. /api/download وقتی خودِ CDN خطایی غیر از 403 / 404 / 410 داده باشد (مثلاً 429 خودش یا 5xx) هم 502 Proxy error می‌دهد؛ آن‌وقت بدنه upstreamStatus و message دارد و Retry-After ندارد.

What to do: retry once; for 403 / 404 / 410 fetch the post again to get a fresh URL.یک بار تکرار کنید؛ برای 403 / 404 / 410 پست را دوباره بگیرید تا لینک تازه بگیرید.

{ "error": "Proxy error" }

{ "error": "Proxy error", "upstreamStatus": 429, "message": "The Instagram CDN answered 429. Retry once; if it fails again, fetch the post again for a fresh URL." }

The Instagram CDN refused the file URL (403), no longer has it (404) or says it is gone (410). The status is the CDN's own; upstreamStatus repeats it. CDN URLs are signed and expire after a while, so this usually means the URL came from an older response. It is never the server's limit and never about your key.CDN اینستاگرام آدرس فایل را رد کرد (403)، دیگر آن را ندارد (404) یا می‌گوید حذف شده (410). کد همان کدِ خودِ CDN است و upstreamStatus آن را تکرار می‌کند. آدرس‌های CDN امضاشده‌اند و بعد از مدتی منقضی می‌شوند؛ پس معمولاً یعنی آدرس از پاسخی قدیمی آمده. هیچ‌وقت محدودیت سرور یا مشکل کلید شما نیست.

What to do: do not retry the same URL: fetch the post, story or highlight again and download its fresh URL.همان آدرس را تکرار نکنید: پست، استوری یا هایلایت را دوباره بگیرید و آدرس تازه‌اش را دانلود کنید.

{ "error": "Link expired", "upstreamStatus": 403, "message": "The Instagram CDN answered 403: this link has expired or the file is gone. Fetch the post again for a fresh URL." }

Too many image or download requests in progress on the whole server; yours waited up to 10 s for a free slot. Retry-After: 2.درخواست تصویر یا دانلودِ در جریان در کل سرور زیاد است؛ درخواست شما تا ۱۰ ثانیه برای جای خالی صبر کرد. Retry-After: 2.

What to do: wait 2 s and retry; load fewer images at once.۲ ثانیه صبر و تکرار کنید؛ تصویرهای کمتری را هم‌زمان بگیرید.

{ "error": "busy", "message": "Too many image requests in progress on this server — retry in a moment.", "retryAfterMs": 2000 }

The API is in maintenance mode; message is our note. Retry-After: 300. GET /api/health then carries "maintenance": true, so a client can poll it for free instead of the data endpoints. Requests with a valid key may be let through during maintenance.API در حالت تعمیر است؛ message یادداشت ماست. Retry-After: 300. در این حالت GET /api/health فیلد "maintenance": true دارد، پس کلاینت می‌تواند به‌جای سرویس‌های داده آن را (رایگان) بپرسد. ممکن است درخواست‌های با کلید معتبر در حالت تعمیر آزاد باشند.

What to do: back off — retry after Retry-After, or poll /api/health until maintenance is gone.عقب بکشید — بعد از Retry-After دوباره بفرستید، یا /api/health را بپرسید تا maintenance برداشته شود.

{ "error": "maintenance", "message": "The API is down for maintenance. Please try again in a few minutes.", "retryAfterMs": 300000 }