Felo APIs

X Search API

کاربران X، توییت‌ها، خطوط زمانی و پاسخ‌ها را با فراداده صفحه‌بندی جستجو کنید.

POST/v2/x/tweet/search

احراز هویت

Bearer API key

نوع محتوا

application/json

یادداشت نرخ

1 request per 10 seconds, 3 per minute, 10 per 10 minutes.

Chat API

X Search API دسترسی به داده‌های X (توییتر) را فراهم می‌کند، از جمله نمایه‌های کاربران، جستجوی توییت، توییت‌های کاربر و پاسخ‌های توییت.

احراز هویت

همه درخواست‌ها به یک کلید API در سرآیند Authorization نیاز دارند:

Authorization: Bearer YOUR_API_KEY

استفاده با عامل‌های هوش مصنوعی

بسته کامل felo-ai را نصب کنید تا X Search و هر Felo Skill در دسترس دیگر به یک عامل داده شود. نصب‌کننده به‌صورت پویا هر پوشه بسته شامل SKILL.md را کشف می‌کند، به‌جای نگه‌داشتن فهرست ثابتی از Skill. همه Skillهای کشف‌شده را در ~/.codex/skills مربوط به Codex، ~/.claude/skills مربوط به Claude Code، ~/.agents/skills مربوط به OpenClaw یا ~/.hermes/skills مربوط به Hermes Agent نصب کنید. برای نصب مخصوص هر پلتفرم، کلید API و دستورهای بررسی راهنمای راه‌اندازی دستی عامل هوش مصنوعی را ببینید.

1. دریافت اطلاعات کاربر

نمایه‌های کاربران X را دسته‌ای بر اساس نام کاربری دریافت کنید.

Endpoint

POST https://openapi.felo.ai/v2/x/user/info

بدنه درخواست

پارامتر	نوع	الزامی	توضیح
`usernames`	آرایه‌ای از رشته‌ها	بله	فهرست نام‌های کاربری X برای جستجو

نمونه

curl -X POST 'https://openapi.felo.ai/v2/x/user/info' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "usernames": ["elonmusk", "OpenAI"]
  }'

پاسخ موفق (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 2,
    "users": [
      {
        "user_id": "44196397",
        "username": "elonmusk",
        "display_name": "Elon Musk",
        "description": "...",
        "followers_count": 100000000,
        "following_count": 500,
        "tweet_count": 30000,
        "verified": true,
        "blue_verified": true,
        "profile_image_url": "https://pbs.twimg.com/...",
        "created_at": "2009-06-02T00:00:00Z",
        "location": "Mars"
      }
    ]
  }
}

فیلدهای شیء کاربر

فیلد	نوع	توضیح
`user_id`	string	شناسه کاربر X
`username`	string	نام کاربری X (بدون @)
`display_name`	string	نام نمایشی
`description`	string	بیوی کاربر
`followers_count`	integer	شمار دنبال‌کنندگان
`following_count`	integer	شمار دنبال‌شده‌ها
`tweet_count`	integer	کل توییت‌ها
`verified`	boolean	تأییدشده بودن حساب
`blue_verified`	boolean	داشتن تأیید Blue
`verified_type`	string	نوع تأیید
`profile_image_url`	string	URL تصویر نمایه
`cover_image_url`	string	URL تصویر کاور
`created_at`	string	زمان ساخت حساب
`location`	string	موقعیت کاربر
`url`	string	URL وب‌سایت کاربر
`protected`	boolean	محافظت‌شده بودن حساب
`favorites_count`	integer	شمار پسندها
`media_count`	integer	شمار پست‌های رسانه‌ای
`can_dm`	boolean	باز بودن DM
`is_automated`	boolean	خودکار بودن حساب
`pinned_tweet_ids`	آرایه‌ای از رشته‌ها	شناسه توییت‌های پین‌شده

2. جستجوی کاربران

کاربران X را بر اساس کلیدواژه جستجو کنید.

Endpoint

POST https://openapi.felo.ai/v2/x/user/search

بدنه درخواست

پارامتر	نوع	الزامی	توضیح
`query`	string	بله	کلیدواژه جستجو
`cursor`	string	خیر	مکان‌نمای صفحه‌بندی از پاسخ پیشین

نمونه

curl -X POST 'https://openapi.felo.ai/v2/x/user/search' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "artificial intelligence"
  }'

پاسخ موفق (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 50,
    "has_next": true,
    "next_cursor": "cursor_abc123",
    "users": [
      {
        "user_id": "...",
        "username": "...",
        "display_name": "..."
      }
    ]
  }
}

فیلدهای پاسخ

فیلد	نوع	توضیح
`total`	integer	شمار کل نتایج
`has_next`	boolean	در دسترس بودن نتایج بیشتر
`next_cursor`	string	مکان‌نمای صفحه بعد
`users`	array	فهرست اشیاء کاربر (بخش 1 را ببینید)

3. دریافت توییت‌های کاربر

توییت‌های یک کاربر مشخص X را دریافت کنید.

Endpoint

POST https://openapi.felo.ai/v2/x/user/tweets

بدنه درخواست

پارامتر	نوع	الزامی	توضیح
`x_user_id`	string	خیر	شناسه کاربر X (یکی از `x_user_id` یا `username` را بدهید)
`username`	string	خیر	نام کاربری X (یکی از `x_user_id` یا `username` را بدهید)
`limit`	integer	خیر	شمار توییت‌های برگشتی
`cursor`	string	خیر	مکان‌نمای صفحه‌بندی
`include_replies`	boolean	خیر	گنجاندن پاسخ‌ها

نمونه

curl -X POST 'https://openapi.felo.ai/v2/x/user/tweets' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "elonmusk",
    "limit": 20
  }'

پاسخ موفق (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 20,
    "has_next": true,
    "next_cursor": "cursor_def456",
    "tweets": [
      {
        "id": "1234567890",
        "content": "Tweet content here...",
        "author": { "user_id": "...", "username": "elonmusk" },
        "created_at": "2026-03-09T12:00:00Z",
        "metrics": {
          "retweet_count": 1000,
          "favorite_count": 5000,
          "reply_count": 200,
          "quote_count": 100,
          "view_count": 500000,
          "bookmark_count": 50
        },
        "hashtags": ["AI"],
        "mentions": ["OpenAI"],
        "url": "https://x.com/elonmusk/status/1234567890",
        "lang": "en"
      }
    ]
  }
}

فیلدهای شیء توییت

فیلد	نوع	توضیح
`id`	string	شناسه توییت
`content`	string	محتوای متنی توییت
`author`	object	شیء کاربر نویسنده (بخش 1 را ببینید)
`created_at`	string	زمان ساخت توییت
`metrics`	object	معیارهای تعامل (پایین را ببینید)
`replies`	array	توییت‌های پاسخ (در صورت وجود)
`conversation_id`	string	شناسه رشته گفت‌وگو
`media_urls`	array	رسانه پیوست‌شده
`hashtags`	آرایه‌ای از رشته‌ها	هشتگ‌های توییت
`mentions`	آرایه‌ای از رشته‌ها	نام‌های کاربری اشاره‌شده
`urls`	آرایه‌ای از رشته‌ها	URLهای داخل توییت
`url`	string	پیوند دائمی توییت
`source`	string	منبع توییت (مثلاً "Twitter Web App")
`lang`	string	کد زبان توییت
`is_reply`	boolean	پاسخ بودن این توییت
`in_reply_to_id`	string	شناسه توییتی که به آن پاسخ داده شده
`in_reply_to_user_id`	string	شناسه کاربر توییتی که به آن پاسخ داده شده
`in_reply_to_username`	string	نام کاربری توییتی که به آن پاسخ داده شده
`quoted_tweet`	object	شیء توییت نقل‌شده (بازگشتی)
`retweeted_tweet`	object	شیء توییت بازتوییت‌شده (بازگشتی)
`is_limited_reply`	boolean	محدود بودن پاسخ‌ها

فیلدهای شیء معیارها

فیلد	نوع	توضیح
`retweet_count`	integer	شمار بازتوییت‌ها
`favorite_count`	integer	شمار پسندها
`reply_count`	integer	شمار پاسخ‌ها
`quote_count`	integer	شمار نقل‌قول‌ها
`view_count`	integer	شمار بازدیدها
`bookmark_count`	integer	شمار نشانک‌ها

4. جستجوی توییت‌ها

توییت‌های X را بر اساس کلیدواژه با پشتیبانی از پرس‌وجوهای پیشرفته جستجو کنید.

Endpoint

POST https://openapi.felo.ai/v2/x/tweet/search

بدنه درخواست

پارامتر	نوع	الزامی	توضیح
`query`	string	بله	پرس‌وجوی جستجو (از نحو جستجوی پیشرفته پشتیبانی می‌کند)
`query_type`	string	خیر	فیلتر نوع پرس‌وجو
`since_time`	integer	خیر	فیلتر زمان شروع (برچسب زمانی Unix به ثانیه)
`until_time`	integer	خیر	فیلتر زمان پایان (برچسب زمانی Unix به ثانیه)
`limit`	integer	خیر	شمار توییت‌های برگشتی
`cursor`	string	خیر	مکان‌نمای صفحه‌بندی

نمونه

curl -X POST 'https://openapi.felo.ai/v2/x/tweet/search' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "artificial intelligence",
    "limit": 20
  }'

پاسخ موفق (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 20,
    "has_next": true,
    "next_cursor": "cursor_ghi789",
    "tweets": [
      {
        "id": "...",
        "content": "...",
        "author": { "user_id": "...", "username": "..." },
        "created_at": "2026-03-09T12:00:00Z",
        "metrics": { "retweet_count": 100, "favorite_count": 500 }
      }
    ]
  }
}

فیلدهای پاسخ

فیلد	نوع	توضیح
`total`	integer	شمار کل نتایج
`has_next`	boolean	در دسترس بودن نتایج بیشتر
`next_cursor`	string	مکان‌نمای صفحه بعد
`tweets`	array	فهرست اشیاء توییت (بخش 3 را ببینید)

5. دریافت پاسخ‌های توییت

پاسخ‌های توییت‌های مشخص را دریافت کنید.

Endpoint

POST https://openapi.felo.ai/v2/x/tweet/replies

بدنه درخواست

پارامتر	نوع	الزامی	توضیح
`tweet_ids`	آرایه‌ای از رشته‌ها	بله	شناسه توییت‌ها برای دریافت پاسخ‌ها
`cursor`	string	خیر	مکان‌نمای صفحه‌بندی
`since_time`	integer	خیر	فیلتر زمان شروع (برچسب زمانی Unix)
`until_time`	integer	خیر	فیلتر زمان پایان (برچسب زمانی Unix)

نمونه

curl -X POST 'https://openapi.felo.ai/v2/x/tweet/replies' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "tweet_ids": ["1234567890"]
  }'

پاسخ موفق (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "results": [
      {
        "tweet_id": "1234567890",
        "total": 10,
        "has_next": true,
        "next_cursor": "cursor_jkl012",
        "replies": [
          {
            "id": "...",
            "content": "Great tweet!",
            "author": { "user_id": "...", "username": "..." },
            "created_at": "2026-03-09T12:30:00Z"
          }
        ]
      }
    ]
  }
}

فیلدهای پاسخ

فیلد	نوع	توضیح
`results`	array	فهرست اشیاء نتیجه پاسخ
`results[].tweet_id`	string	شناسه توییت اصلی
`results[].total`	integer	شمار کل پاسخ‌ها
`results[].has_next`	boolean	در دسترس بودن پاسخ‌های بیشتر
`results[].next_cursor`	string	مکان‌نمای صفحه بعد
`results[].replies`	array	فهرست اشیاء توییت پاسخ (بخش 3 را ببینید)

کدهای خطا

کد	وضعیت HTTP	توضیح
`UNAUTHORIZED`	401	کلید API نامعتبر یا لغوشده است
`X_SEARCH_FAILED`	400/500	درخواست جستجوی X شکست خورد (پارامترها یا خطای پایین‌دستی را بررسی کنید)
`RATE_LIMIT_EXCEEDED`	429	درخواست‌های بیش از حد؛ لطفاً پس از تأخیری کوتاه دوباره تلاش کنید
`insufficient_credits`	402	اعتبار کافی برای تکمیل درخواست نیست

اعتبار و محدودیت نرخ

هزینه اعتبار

هر فراخوانی API بر اساس شمار نتایج برگشتی از اعتبار کسر می‌کند:

Endpoint	هزینه اعتبار
`POST /x/user/info`	1 اعتبار برای هر کاربر برگشتی
`POST /x/user/search`	1 اعتبار برای هر کاربر برگشتی
`POST /x/user/tweets`	1 اعتبار برای هر توییت برگشتی
`POST /x/tweet/search`	1 اعتبار برای هر توییت برگشتی
`POST /x/tweet/replies`	1 اعتبار برای هر پاسخ برگشتی

اعتبار پس از تکمیل درخواست و بر اساس شمار واقعی نتایج کسر می‌شود. اگر درخواست 0 نتیجه برگرداند، اعتباری کسر نمی‌شود.

الزام کمینه مانده: حساب شما باید دست‌کم 10 اعتبار داشته باشد تا بتواند هر درخواست X API انجام دهد. درخواست‌هایی با کمتر از 10 اعتبار با HTTP 402 رد می‌شوند.

محدودیت نرخ

محدودیت‌های نرخ بر اساس سیاست‌های جاری سرویس API و حساب اعمال می‌شوند. هنگام محدودیت نرخ، API کد HTTP 429 برمی‌گرداند. سرآیند Retry-After زمان انتظار پیشنهادی را به ثانیه نشان می‌دهد. برای مدیریت محدودیت‌های نرخ از آخرین مستندات سرویس و پاسخ‌های واقعی API استفاده کنید؛ برای استفاده از پلتفرم اشتراک لازم نیست.