مستندات فنی سرویس CoCo Instagram API

۱. معرفی سرویس

سرویس CoCo Instagram API داده‌های عمومی و لحظه‌ای اینستاگرام را در اختیار شما قرار می‌دهد:

سرویس از دو پروتکل پشتیبانی می‌کند و هر دو به داده‌ها و قابلیت‌های یکسانی دسترسی دارند:

• REST — برای فراخوانی مستقیم از کد برنامهٔ شما (هر زبان برنامه‌نویسی).
• MCP (Model Context Protocol) — برای اتصال مستقیم دستیارها و ایجنت‌های هوش مصنوعی (مانند Claude، Cursor، VS Code و ایجنت‌های اختصاصی) به سرویس، بدون نیاز به نوشتن کد.

۲. نحوهٔ کار سرویس

برنامهٔ شما (REST)  ─┐
                      ├──►  CoCo API  ──►  احراز هویت با API Key و بررسی اعتبار
دستیار هوش مصنوعی (MCP) ─┘        │
                                  ├──►  دریافت دادهٔ لحظه‌ای از اینستاگرام
                                  ├──►  ثبت درخواست و کسر اعتبار
                                  └──►  پاسخ JSON

1. هر درخواست باید هدر x-api-key را داشته باشد.
2. سرویس کلید را بررسی می‌کند: معتبر بودن، فعال بودن حساب و کافی بودن اعتبار.
3. داده به‌صورت لحظه‌ای از اینستاگرام دریافت و در قالب JSON برگردانده می‌شود (داده‌ها کش نمی‌شوند).
4. درخواست ثبت و هزینهٔ آن از اعتبار حساب شما کسر می‌شود (جزئیات در اعتبار و هزینه).

۳. دریافت API Key

برای دریافت API Key و خرید یا افزایش اعتبار، با تیم پشتیبانی کوکو از طریق وب‌سایت coco.gl تماس بگیرید. پس از ثبت حساب، موارد زیر به شما تحویل داده می‌شود:

• API Key: یک شناسهٔ UUID، مانند 3f6c2a1e-8b4d-4e7a-9c1f-2d5e8a7b6c40
• میزان اعتبار (Credit) حساب

۴. مفاهیم مشترک

این بخش برای هر دو پروتکل REST و MCP یکسان است.

۴.۱. آدرس‌ها

۴.۲. احراز هویت

همهٔ درخواست‌ها باید هدر زیر را داشته باشند:

x-api-key: <YOUR_API_KEY>

۴.۳. اعتبار (Credit) و هزینه

• هزینهٔ هر فراخوانی ۱ اعتبار است (در REST و MCP یکسان).
• هر صفحه از نتایج صفحه‌بندی‌شده، یک فراخوانی جداگانه محسوب می‌شود.

۴.۴. صفحه‌بندی (Pagination)

سرویس‌های پست‌های اخیر، کامنت‌ها، فالوورها و فالووینگ‌ها صفحه‌بندی‌شده هستند:

1. درخواست اول را بدون pagination_token ارسال کنید.
2. پاسخ شامل فیلد paginationToken است.
3. برای صفحهٔ بعد، همان درخواست را با پارامترهای قبلی و pagination_token=<مقدار دریافتی> تکرار کنید.
4. اگر paginationToken برابر null یا خالی باشد، صفحهٔ دیگری وجود ندارد.

۴.۵. قالب داده‌ها

• همهٔ پاسخ‌ها با Content-Type: application/json و کدگذاری UTF-8 هستند.
• فیلد زمان (created_at) به‌صورت Unix timestamp به ثانیه (UTC) است.
• شناسه‌ها (id، user_id) عدد صحیح ۶۴ بیتی هستند. در زبان‌هایی مثل JavaScript آن‌ها را با BigInt یا به‌صورت رشته پردازش کنید تا دقت عدد از بین نرود.
• فیلدهای بدون مقدار با null برگردانده می‌شوند (فیلد حذف نمی‌شود).

۴.۶. لینک‌های تصویر و ویدیو

برای نمایش یا ذخیرهٔ رسانه، لینک‌های downloadable* را بدون تغییر استفاده کنید.

۴.۷. ورودی‌ها

۵. مدل‌های داده

مدل‌های زیر در پاسخ چند سرویس تکرار می‌شوند و در ادامه با نامشان به آن‌ها ارجاع داده شده است.

UserLight — اطلاعات خلاصهٔ کاربر

Post — پست

Slide — آیتم پست چندتایی

۶. REST API

همهٔ مسیرها نسبت به https://coco.gl/api/api هستند و پارامترها به‌صورت Query String ارسال می‌شوند. در پاسخ‌های موفق، داده مستقیماً در بدنهٔ پاسخ قرار دارد. قالب پاسخ خطا در کدهای خطا آمده است. مقادیر نمونه‌ها صرفاً برای نمایش ساختار هستند و برخی آرایه‌ها کوتاه شده‌اند.

۶.۱. اطلاعات پروفایل

GET /scrapper/instagram/user

نمونهٔ درخواست

curl -H "x-api-key: YOUR_API_KEY" \
  "https://coco.gl/api/api/scrapper/instagram/user?username=nasa"

نمونهٔ پاسخ

{
  "username": "nasa",
  "user_id": 528817151,
  "full_name": "NASA",
  "profile_pic_url": "https://scontent.cdninstagram.com/v/t51.2885-19/...jpg",
  "post_count": 4512,
  "follower_count": 104415396,
  "following_count": 79,
  "bio": "Exploring the universe and our home planet.",
  "external_url": "https://www.nasa.gov",
  "is_private": false,
  "is_verified": true,
  "is_business_account": null,
  "category": "Government organization"
}

۶.۲. جست‌وجوی کاربر

GET /scrapper/instagram/user/search

فقط حساب‌هایی برگردانده می‌شوند که نام کاربری‌شان شامل عبارت جست‌وجو باشد. در صورت نبود نتیجه، آرایهٔ خالی برگردانده می‌شود.

نمونهٔ درخواست

curl -H "x-api-key: YOUR_API_KEY" \
  "https://coco.gl/api/api/scrapper/instagram/user/search?username=nasa"

نمونهٔ پاسخ

آرایه‌ای از UserLight

[
  {
    "id": 528817151,
    "username": "nasa",
    "fullName": "NASA",
    "isVerified": true,
    "profilePicUrl": "https://scontent.cdninstagram.com/v/t51.2885-19/...jpg"
  },
  {
    "id": 1612839480,
    "username": "nasahubble",
    "fullName": "Hubble Space Telescope",
    "isVerified": true,
    "profilePicUrl": "https://scontent.cdninstagram.com/v/t51.2885-19/...jpg"
  }
]

۶.۳. پست‌های اخیر

GET /scrapper/instagram/posts/recent

پست‌ها از جدید به قدیم مرتب شده‌اند؛ پست‌های پین‌شده ممکن است در ابتدا قرار بگیرند.

نمونهٔ درخواست

curl -H "x-api-key: YOUR_API_KEY" \
  "https://coco.gl/api/api/scrapper/instagram/posts/recent?username=nasa"

نمونهٔ پاسخ

posts آرایه‌ای از Post

{
  "posts": [
    {
      "id": 4004634989362489982,
      "shortcode": "DeTUk4sDSp-",
      "caption": "POV: you're watching the Earth set...",
      "type": "VIDEO",
      "likeCount": 773422,
      "commentCount": 7766,
      "thumbnailUrl": "https://scontent.cdninstagram.com/v/t51.71878-15/...jpg",
      "downloadableThumbnailUrl": "https://coco.gl/api/api/media/download?link=aHR0cHM6Ly9...",
      "videoUrl": "https://scontent.cdninstagram.com/o1/v/t16/...mp4",
      "downloadableVideoUrl": "https://coco.gl/api/api/media/video?link=aHR0cHM6Ly9...",
      "isPaidPartnership": false,
      "isCommentDisabled": false,
      "created_at": 1791645302,
      "sponsors": null,
      "taggedUsers": null,
      "slides": [],
      "dimensions": { "height": 1920, "width": 1080 }
    }
  ],
  "paginationToken": "BE1fBDYpDBZfZR5VGVVRRRFKC0Y-Qz"
}

صفحهٔ بعد

curl -H "x-api-key: YOUR_API_KEY" \
  "https://coco.gl/api/api/scrapper/instagram/posts/recent?username=nasa&pagination_token=BE1fBDYpDBZfZR5VGVVRRRFKC0Y-Qz"

۶.۴. جزئیات پست

GET /scrapper/instagram/posts/detail

نمونهٔ درخواست

curl -H "x-api-key: YOUR_API_KEY" \
  "https://coco.gl/api/api/scrapper/instagram/posts/detail?shortcode=DeTUk4sDSp-"

نمونهٔ پاسخ

{
  "id": 4004634989362489982,
  "shortcode": "DeTUk4sDSp-",
  "caption": "POV: you're watching the Earth set...",
  "type": "VIDEO",
  "likeCount": 773422,
  "commentCount": 7766,
  "playCount": 11329586,
  "thumbnailUrl": "https://scontent.cdninstagram.com/v/t51.71878-15/...jpg",
  "downloadableThumbnailUrl": "https://coco.gl/api/api/media/download?link=aHR0cHM6Ly9...",
  "permalink": "https://instagram.com/p/DeTUk4sDSp-",
  "created_at": 1791645302,
  "owner": {
    "id": 528817151,
    "username": "nasa",
    "fullName": "NASA",
    "isVerified": true,
    "profilePicUrl": "https://scontent.cdninstagram.com/v/t51.2885-19/...jpg"
  }
}

۶.۵. کامنت‌های پست

GET /scrapper/instagram/posts/comments

نمونهٔ درخواست

curl -H "x-api-key: YOUR_API_KEY" \
  "https://coco.gl/api/api/scrapper/instagram/posts/comments?shortcode=DeTUk4sDSp-"

نمونهٔ پاسخ

{
  "count": 7766,
  "comments": [
    {
      "text": "Absolutely stunning view!",
      "user": {
        "id": 1676128850,
        "username": "space_fan",
        "fullName": "Space Fan",
        "isVerified": false,
        "profilePicUrl": "https://scontent.cdninstagram.com/v/t51.2885-19/...jpg"
      }
    }
  ],
  "paginationToken": "BE1fBDYTDBtffUZDRgpHE0YeVh9YQG"
}

۶.۶. فالوورها

GET /scrapper/instagram/user/followers

نمونهٔ درخواست

curl -H "x-api-key: YOUR_API_KEY" \
  "https://coco.gl/api/api/scrapper/instagram/user/followers?username=nasa"

نمونهٔ پاسخ

followers آرایه‌ای از UserLight

{
  "followers": [
    {
      "id": 57735874553,
      "username": "sample_follower",
      "fullName": "Sample Follower",
      "isVerified": false,
      "profilePicUrl": "https://scontent.cdninstagram.com/v/t51.82787-19/...jpg"
    }
  ],
  "paginationToken": null
}

۶.۷. فالووینگ‌ها

GET /scrapper/instagram/user/followings

ورودی‌ها مشابه فالوورها است.

نمونهٔ درخواست

curl -H "x-api-key: YOUR_API_KEY" \
  "https://coco.gl/api/api/scrapper/instagram/user/followings?username=nasa"

نمونهٔ پاسخ

followings آرایه‌ای از UserLight

{
  "followings": [
    {
      "id": 54688074404,
      "username": "astro_frankrubio",
      "fullName": "Francisco Rubio",
      "isVerified": true,
      "profilePicUrl": "https://scontent.cdninstagram.com/v/t51.2885-19/...jpg"
    }
  ],
  "paginationToken": "GU1bCzYpEwdaLFwTTV4FIQA1LCMPRC"
}

۷. MCP (Model Context Protocol)

MCP پروتکلی استاندارد برای اتصال ابزارها به مدل‌های هوش مصنوعی است. با اتصال سرور MCP کوکو به دستیار هوش مصنوعی خود، می‌توانید درخواست‌هایی مانند «۵ پست آخر nasa را با تعداد لایک‌ها مقایسه کن» را به زبان طبیعی مطرح کنید و دستیار خودش ابزار مناسب را فراخوانی می‌کند.

۷.۱. مشخصات سرور

اتصال به سرور و دریافت فهرست ابزارها هزینه‌ای ندارد و فقط فراخوانی ابزارها مشمول قوانین اعتبار است. کلید API هنگام فراخوانی ابزار بررسی می‌شود.

۷.۲. ابزارها

هر ابزار معادل یکی از سرویس‌های REST است و همان خروجی را برمی‌گرداند:

هر ابزار شامل توضیح کامل، JSON Schema ورودی و خروجی و راهنمای استفاده است. دستیار هوش مصنوعی این اطلاعات را هنگام اتصال به‌طور خودکار دریافت می‌کند.

۷.۳. اتصال کلاینت‌ها

Claude Code

claude mcp add --transport http coco https://coco.gl/api/api/mcp --header "x-api-key: YOUR_API_KEY"

Cursor — فایل ~/.cursor/mcp.json

{
  "mcpServers": {
    "coco": {
      "url": "https://coco.gl/api/api/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

VS Code — فایل .vscode/mcp.json

{
  "servers": {
    "coco": {
      "type": "http",
      "url": "https://coco.gl/api/api/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

سایر کلاینت‌ها و ایجنت‌های اختصاصی (مثلاً با SDKهای رسمی MCP در Python، TypeScript یا Java) نیز با همین آدرس و هدر متصل می‌شوند.

۷.۴. فراخوانی مستقیم (JSON-RPC)

برای ایجنت‌هایی که بدون SDK پیاده‌سازی می‌شوند، پیام‌ها در قالب JSON-RPC 2.0 و با متد POST ارسال می‌شوند. هدرهای لازم:

Content-Type: application/json
Accept: application/json, text/event-stream
x-api-key: YOUR_API_KEY

۱. شروع ارتباط (initialize)

curl -X POST "https://coco.gl/api/api/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": { "listChanged": false } },
    "serverInfo": { "name": "coco-api", "version": "1.0.0" },
    "instructions": "CoCo Instagram scrapper: live, public Instagram data ..."
  }
}

۲. فهرست ابزارها (tools/list)

curl -X POST "https://coco.gl/api/api/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

پاسخ شامل name، title، description، inputSchema و outputSchema هر ابزار است.

۳. فراخوانی ابزار (tools/call)

curl -X POST "https://coco.gl/api/api/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_post_detail","arguments":{"shortcode":"DeTUk4sDSp-"}}}'

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "isError": false,
    "structuredContent": {
      "id": 4004634989362489982,
      "shortcode": "DeTUk4sDSp-",
      "type": "VIDEO",
      "likeCount": 773422,
      "commentCount": 7766,
      "playCount": 11329586,
      "...": "..."
    },
    "content": [
      { "type": "text", "text": "{\"id\":4004634989362489982,\"shortcode\":\"DeTUk4sDSp-\", ...}" }
    ]
  }
}

• structuredContent: خروجی به‌صورت شیء JSON، مطابق outputSchema ابزار.
• content: همان خروجی به‌صورت متن JSON، برای کلاینت‌هایی که از structuredContent پشتیبانی نمی‌کنند.

۷.۵. خطا در MCP

خطاهای اجرای ابزار در قالب نتیجهٔ عادی و با isError: true برگردانده می‌شوند. متن خطا همان پیام‌های کدهای خطا است:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "isError": true,
    "content": [ { "type": "text", "text": "Post not found." } ]
  }
}

ورودی نامعتبر (مثلاً ارسال نکردن پارامتر الزامی) پیش از اجرا رد می‌شود و هزینه‌ای ندارد:

{ "type": "text", "text": "Tool (get_post_detail) input validation failed: ... required property 'shortcode' not found" }

۸. کدهای خطا

در REST، پاسخ خطا با کد وضعیت HTTP زیر و بدنهٔ یکسان برگردانده می‌شود:

{
  "success": false,
  "message": "Username not found.",
  "entity": null
}

در خطای Validation failed، فیلد entity نام پارامتر و علت خطا را مشخص می‌کند:

{
  "success": false,
  "message": "Validation failed",
  "entity": { "username": "username should not be blank" }
}

در MCP همین پیام‌ها در content نتیجه با isError: true برگردانده می‌شوند (بخش ۷.۵).

۹. نکات و سؤالات متداول