# بيانات X

استرجع ملفات تعريف X، وابحث عن المستخدمين والمنشورات، واعمِل ترقيمًا للخط الزمني والردود.

اختر العملية الخاصة بالبيانات التي تحتاجها. تستخدم النقاط الخمس جميعها POST وتعيد JSON في الجذر، من دون غلاف `data` مشترك.

تستخدم جميع الأمثلة `FELO_API_KEY` من [نظرة عامة](https://openapi.felo.ai/ar/docs/data-api/guides/felo-overview.md). تستخدم الاستدعاءات **رصيد المنصة**، وليس أرصدة Felo Pro. أمثلة الاستجابة توضيحية؛ ويختلف المحتوى الحي والحقول الاختيارية.

## اختر عملية

| الحاجة | نقطة النهاية |
|---|---|
| ملفات التعريف لأسماء المستخدمين المعروفة | `POST /api/v1/data/x/user/info` |
| العثور على مستخدمين بواسطة استعلام بحث | `POST /api/v1/data/x/user/search` |
| منشورات مستخدم واحد | `POST /api/v1/data/x/user/tweets` |
| منشورات تطابق استعلامًا | `POST /api/v1/data/x/tweet/search` |
| الردود على منشورات معروفة | `POST /api/v1/data/x/tweet/replies` |

## 1. احصل على ملفات تعريف المستخدمين

`POST /api/v1/data/x/user/info`

| الحقل | النوع | مطلوب | المعنى |
|---|---|---|---|
| `usernames` | string array | نعم | من 1 إلى 100 اسم مستخدم؛ أرسل المعرّفات بدون `@` |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/info" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["OpenAI"]}'
```

تحتوي الاستجابة على `users` و`total`. يتضمن كل مستخدم `user_id` و`username` و`display_name`; وقد يظهر أيضًا نص الملف الشخصي، وأعداد المتابعين، وحالة التحقق، وبيانات وصفية أخرى. يمكن أن تُرجع الدفعة أقل من عدد الملفات الشخصية المطلوبة. طابِق باستخدام اسم المستخدم أو المعرف، وليس بحسب موضع المصفوفة.

```json
{"users":[{"user_id":"example-user-id","username":"example","display_name":"Example"}],"total":1}
```

## 2. ابحث عن المستخدمين

`POST /api/v1/data/x/user/search`

| الحقل | النوع | مطلوب | المعنى |
|---|---|---|---|
| `query` | string | نعم | 1–1,000 حرف |
| `cursor` | string | لا | مؤشر ترقيم، حتى 4,000 حرف |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"AI research"}'
```

تحتوي الاستجابة على `users` و`total` و`has_next` و`next_cursor`. لا يوجد معامل `limit` في هذه العملية.

```json
{"users":[],"total":0,"has_next":false,"next_cursor":null}
```

## 3. احصل على الخط الزمني لمستخدم

`POST /api/v1/data/x/user/tweets`

| الحقل | النوع | مطلوب | المعنى |
|---|---|---|---|
| `username` | string | مطلوب مُعرّف واحد | معرّف المستخدم، حتى 100 حرف |
| `x_user_id` | string | مطلوب مُعرّف واحد | معرّف المستخدم، حتى 100 حرف؛ وله أولوية على `username` |
| `limit` | integer | لا | 1–1,000؛ يستخدم التنفيذ الحالي 20 على الأقل، مع افتراضي 20 |
| `cursor` | string | لا | مؤشر ترقيم، حتى 4,000 حرف |
| `include_replies` | boolean | لا | تضمين الردود المتداخلة؛ الافتراضي `false` |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/tweets" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"OpenAI","limit":20,"include_replies":false}'
```

تحتوي الاستجابة على `tweets` و`total` و`has_next` و`next_cursor`. ضبط `limit` على أقل من 20 لا يضمن عدد عناصر أقل مُعادة أو فاتورة أصغر. قد يؤدي تضمين الردود إلى إضافة بيانات مُعادة ونتائج قابلة للفوترة.

### حدود النتائج والردود المتداخلة

`limit` هو عدد مستهدف للمنشورات من المستوى الأعلى لهذا الطلب، وليس عدد نتائج مضمونًا. يستخدم التنفيذ الحالي هدفًا لا يقل عن 20: إذ يقرأ هدف 20 صفحةً أصلية واحدة؛ وتتولى الأهداف الأكبر جلب ما يصل إلى 50 صفحة تلقائيًا. قبل كل صفحة، يُفحص الوقت المنقضي ويتوقف الجلب عن صفحات إضافية بمجرد تجاوزه 60 ثانية. هذا الفحص ليس ضمانًا بأن طلب HTTP الكامل سينتهي خلال 60 ثانية.

يتوقف الجمع أيضًا عندما يتحقق الهدف، أو لا تحتوي الصفحة الأصلية على صفحة تالية، أو تكون الصفحة فارغة، أو يكون المؤشر مفقودًا. لذلك قد تحتوي الاستجابة الناجحة على عدد أقل من `limit` من المنشورات. استخدم `has_next` و`next_cursor` للمتابعة عند توفرهما.

مع `include_replies=true`، تحصل كل منشور مُعاد على ما يصل إلى 5 صفحات إضافية وبحد أقصى 100 رد متداخل. يمكن أن يتوقف الجمع مبكرًا عندما لا توجد صفحة تالية، أو تكون الصفحة فارغة، أو يتعذر على المؤشر التقدم. هذه الردود المتداخلة خارج `limit` و`total` للمستوى الأعلى، لكنها قد تضيف نتائج قابلة للفوترة.

الردود المتداخلة `replies` ليست أرشيفًا كاملًا للردود ولا تكشف عن مؤشر متابعة منفصل لهذا الجمع الإضافي. لترقيم الردود بشكل مستقل، استخدم عملية قراءة الردود والمؤشر المُعاد منها. لا تعِد استخدام مؤشر منشور المستوى الأعلى للردود.

## 4. ابحث عن المنشورات

`POST /api/v1/data/x/tweet/search`

| الحقل | النوع | مطلوب | المعنى |
|---|---|---|---|
| `query` | string | نعم | نص البحث، 1–1,000 حرف |
| `query_type` | string | لا | `Latest` (الافتراضي) أو `Top` |
| `limit` | integer | لا | 1–1,000؛ يستخدم التنفيذ الحالي 20 على الأقل، مع افتراضي 20 |
| `cursor` | string | لا | مؤشر ترقيم، حتى 4,000 حرف |
| `since_time` | integer or string | لا | وقت البدء؛ استخدم ثواني Unix لقيمة رقمية غير ملتبسة |
| `until_time` | integer or string | لا | وقت الانتهاء؛ استخدم ثواني Unix، وليس المللي ثانية |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/tweet/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"retrieval augmented generation","query_type":"Latest","limit":20}'
```

تحتوي الاستجابة على `tweets` و`total` و`has_next` و`next_cursor`. تتضمن كائنات المنشورات `id` و`content` و`author` و`created_at` و`metrics`; وقد تكون الردود والمنشورات المقتبسة/المعاد نشرها متداخلة. عامِل المعرفات كسلاسل نصية.

### حدود عدد النتائج

`limit` هو هدف، وليس ضمانًا. يستخدم التنفيذ الحالي هدفًا لا يقل عن 20: إذ يقرأ هدف 20 صفحة أصلية واحدة؛ وتتولى الأهداف الأكبر جلب ما يصل إلى 50 صفحة تلقائيًا. يُفحص الوقت المنقضي قبل كل صفحة، ولا تُجلب صفحات إضافية بعد تجاوزه 60 ثانية. قد يستغرق طلب upstream الجاري وقتًا إضافيًا، لذا فهذه ليست مهلة HTTP شاملة.

يتوقف الجمع أيضًا عندما يتحقق الهدف، أو لا تحتوي الصفحة الأصلية على صفحة تالية، أو تكون الصفحة فارغة، أو يكون المؤشر مفقودًا. إن إرجاع عدد أقل من `limit` من المنشورات لا يعني فشل الطلب أو أنه تم استرجاع كل منشور مطابق. تحقّق من `has_next` و`next_cursor` قبل المتابعة.

```json
{
  "tweets": [{
    "id":"example-post-id",
    "content":"Example post content",
    "author":{"user_id":"example-user-id","username":"example","display_name":"Example"},
    "created_at":"2026-11-01T00:00:00Z",
    "metrics":{},
    "replies":[]
  }],
  "total":1,
  "has_next":false,
  "next_cursor":null
}
```

## 5. اقرأ الردود

`POST /api/v1/data/x/tweet/replies`

| الحقل | النوع | مطلوب | المعنى |
|---|---|---|---|
| `tweet_ids` | string or string array | نعم | معرّف منشور واحد أو دفعة تصل إلى 20 معرّفًا |
| `cursor` | string | لا | حتى 4,000 حرف؛ استخدمه مع معرّف منشور واحد |
| `since_time` | integer | لا | وقت البدء بثواني Unix |
| `until_time` | integer | لا | وقت الانتهاء بثواني Unix |

استبدل العنصر النائب بمعرّف منشور حقيقي:

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/tweet/replies" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tweet_ids":["POST_ID"]}'
```

على خلاف الخط الزمني وبحث المنشورات، تُجمَّع الردود تحت `results`. لكل إدخال حالة ترقيم خاصة به:

```json
{"results":[{"tweet_id":"POST_ID","replies":[],"total":0,"has_next":false,"next_cursor":null}]}
```

### حدود الردود لكل طلب

يقرأ كل طلب صفحة ردود أصلية واحدة لكل `tweet_id` ويحتفظ بما يصل إلى 100 رد؛ ولا يجلب تلقائيًا كل صفحات الردود. في دفعة تصل إلى 20 معرّفًا، ينطبق حد 100 رد بشكل منفصل على كل إدخال في `results`. قد تكون الأعداد الفعلية أقل.

يمثل `total` في كل إدخال عدد الردود المُعادة في ذلك الإدخال، وليس العدد الكامل لردود المنشور. للمتابعة، استخدم `next_cursor` لذلك الإدخال وأرسل فقط معرّف المنشور المفرد الخاص به في الطلب التالي. لا يوجد معامل `limit` لزيادة الحد الأقصى لكل طلب.

## الترقيم والتحكم في التكلفة

يعدّ `total` المصفوفة المقابلة في الاستجابة الحالية: المنشورات ذات المستوى الأعلى في استعلامات المنشورات، أو الردود داخل كل إدخال نتيجة في استعلامات الردود. وهو ليس عدد المطابقات العالمي، ولا العدد الكامل لردود منشور، ولا العدد النهائي القابل للفوترة.

1. أرسل الطلب الأول بدون `cursor`.
2. اقرأ `has_next` و`next_cursor` من الاستجابة. بالنسبة للردود، اقرأهما في كل إدخال نتيجة.
3. إذا كانت هناك صفحة أخرى وكان المؤشر غير فارغ، فأرسله كما هو مع الاستعلام نفسه. بالنسبة لدفعة ردود، واصل كل منشور على حدة.
4. توقّف عندما لا توجد صفحة تالية، أو عندما يتكرر مؤشر، أو عندما تصل إلى حد الصفحة أو الإنفاق الخاص بك.

تعكس بيانات ترقيم الصفحات آخر استجابة أصلية؛ وقد تُقتطع المجموعة المُعادة عند حد أقصى للنتائج. حتى `has_next=false` ليس ضمانًا بأن كل سجل X أو الردود قد استُرجعت. اعرض العدد الفعلي المُعاد بدلًا من وسم مجموعة نتائج محدودة على أنها كل البيانات المتاحة.

يمكن أن تُفْرض رسوم على كل صفحة ناجحة. تُفوتر هذه العمليات الخمس حسب النتائج المُعادة، وليس برسم ثابت لكل طلب. يمكن للردود المتداخلة والسجلات الأخرى المُعادة أن تؤثر في العدد المُفوتر؛ لا تقدّر التكلفة اعتمادًا على طول المصفوفة ذات المستوى الأعلى فقط. تحقّق من [الأسعار الحالية](https://openapi.felo.ai/api/v1/data/prices) والاستخدام في وحدة التحكم. توجد الحقول الكاملة للكائنات في [مخطط OpenAPI](https://openapi.felo.ai/api/v1/data/openapi.json).