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 (Twitter)، بما في ذلك ملفات تعريف المستخدمين والبحث عن التغريدات وتغريدات المستخدم وردود التغريدات.

المصادقة

تتطلب كل الطلبات مفتاح API في رأس Authorization:

Authorization: Bearer YOUR_API_KEY

الاستخدام مع وكلاء الذكاء الاصطناعي

ثبّت حزمة felo-ai الكاملة لتزويد وكيل بميزة X Search وكل مهارة Felo Skill أخرى متاحة. يكتشف المثبّت ديناميكيًا كل دليل حزمة يحتوي SKILL.md، بدلًا من الاحتفاظ بقائمة مهارات ثابتة. ثبّت كل المهارات المكتشفة في Codex ~/.codex/skills أو Claude Code ~/.claude/skills أو OpenClaw ~/.agents/skills أو Hermes Agent ~/.hermes/skills. راجع دليل إعداد وكيل الذكاء الاصطناعي اليدوي لتعليمات التثبيت ومفتاح API والتحقق حسب كل منصة.

1. الحصول على معلومات المستخدم

استرجع ملفات تعريف مستخدمي X دفعةً واحدة حسب اسم المستخدم.

Endpoint

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

نص الطلب

المعامل	النوع	مطلوب	الوصف
`usernames`	array of strings	نعم	قائمة أسماء مستخدمي 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	ما إذا كانت الرسائل المباشرة مفتوحة
`is_automated`	boolean	ما إذا كان الحساب آليًا
`pinned_tweet_ids`	array of strings	معرّفات التغريدات المثبّتة

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`	array of strings	الوسوم في التغريدة
`mentions`	array of strings	أسماء المستخدمين المذكورين
`urls`	array of strings	عناوين 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`	array of strings	نعم	معرّف التغريدة أو التغريدات المطلوب الحصول على ردودها
`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`	رصيد واحد لكل مستخدم مُعاد
`POST /x/user/search`	رصيد واحد لكل مستخدم مُعاد
`POST /x/user/tweets`	رصيد واحد لكل تغريدة مُعادة
`POST /x/tweet/search`	رصيد واحد لكل تغريدة مُعادة
`POST /x/tweet/replies`	رصيد واحد لكل رد مُعاد

تُخصم الأرصدة بعد اكتمال الطلب، بناءً على العدد الفعلي للنتائج. وإذا أعاد الطلب 0 نتيجة، فلا تُخصم أرصدة.

الحد الأدنى للرصيد: يجب أن يحتوي حسابك على 10 أرصدة على الأقل لإجراء أي طلب إلى X API. وتُرفض الطلبات التي تُجرى بأقل من 10 أرصدة بالاستجابة HTTP 402.

حدود المعدل

تُطبّق حدود المعدل وفق سياسات خدمة API والحساب الحالية. عند تجاوز الحد، يعيد API الاستجابة HTTP 429. ويشير رأس Retry-After إلى مدة الانتظار المقترحة بالثواني. استخدم أحدث مستندات الخدمة والاستجابات الفعلية من API للتعامل مع حدود المعدل؛ ولا يلزم اشتراك لاستخدام المنصة.