# נתוני X

אחזר פרופילים מ-X, חפש משתמשים ופוסטים, ודפדף בצירי זמן ובתגובות.

בחרו את הפעולה עבור הנתונים שאתם צריכים. כל חמש נקודות הקצה משתמשות ב-POST ומחזירות JSON בשורש, ללא מעטפת `data` משותפת.

כל הדוגמאות משתמשות ב-`FELO_API_KEY` מתוך [הסקירה הכללית](https://openapi.felo.ai/he/docs/data-api/guides/felo-overview.md). הקריאות משתמשות ב-**יתרת הפלטפורמה**, ולא ב-Felo Pro credits. דוגמאות התגובה הן להמחשה; תוכן חי ושדות אופציונליים משתנים.

## בחרו פעולה

| צורך | נקודת קצה |
|---|---|
| פרופילים עבור שמות משתמש ידועים | `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 | לא | cursor לדפדוף, עד 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 | לא | cursor לדפדוף, עד 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 קורא דף upstream אחד; יעדים גדולים יותר שולפים אוטומטית עד 50 דפים. לפני כל דף, נבדק הזמן שחלף ונעצרת השליפה של דפים נוספים ברגע שהוא עובר 60 שניות. בדיקה זו אינה מבטיחה שכל בקשת HTTP תסתיים בתוך 60 שניות.

הקולקציה גם נעצרת כאשר היעד מושג, ל-upstream אין דף הבא, דף ריק, או שה-cursor חסר. לכן תגובה מוצלחת עשויה להכיל פחות פוסטים מ-`limit`. השתמשו ב-`has_next` וב-`next_cursor` כדי להמשיך כאשר הם זמינים.

עם `include_replies=true`, כל פוסט מוחזר מקבל עד 5 דפים נוספים ולכל היותר 100 תגובות מקוננות. הקולקציה יכולה להיעצר מוקדם יותר כאשר אין דף הבא, דף ריק, או שה-cursor לא יכול להתקדם. תגובות מקוננות אלו נמצאות מחוץ ל-`limit` ול-`total` ברמה העליונה, אך יכולות להוסיף תוצאות מחויבות.

`replies` מקוננים אינם ארכיון תגובות מלא ואינם חושפים cursor המשכיות נפרד לאיסוף נוסף זה. כדי לדפדף תגובות באופן עצמאי, השתמשו בפעולת קריאת תגובות וב-cursor המוחזר שלה. אל תשתמשו מחדש ב-cursor של הפוסט ברמה העליונה עבור תגובות.

## 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 | לא | cursor לדפדוף, עד 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 קורא דף upstream אחד; יעדים גדולים יותר שולפים אוטומטית עד 50 דפים. הזמן שחלף נבדק לפני כל דף, ולא נשלפים דפים נוספים לאחר שהוא עובר 60 שניות. בקשת upstream שבאוויר עדיין יכולה לקחת זמן, לכן זה אינו timeout HTTP כולל.

הקולקציה גם נעצרת כאשר היעד מושג, ל-upstream אין דף הבא, דף ריק, או שה-cursor חסר. החזרת פחות פוסטים מ-`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}]}
```

### מגבלות תגובות לכל בקשה

כל בקשה קוראת דף תגובות אחד upstream לכל `tweet_id` ושומרת לכל היותר 100 תגובות; היא אינה שולפת אוטומטית כל דף תגובה. באצווה של עד 20 מזהים, מגבלת 100 התגובות חלה בנפרד על כל רשומת `results`. הכמויות בפועל יכולות להיות נמוכות יותר.

ה-`total` של כל רשומה הוא מספר התגובות שהוחזרו באותה רשומה, לא מספר התגובות המלא של הפוסט. כדי להמשיך, השתמשו ב-`next_cursor` של אותה רשומה ושלחו רק את מזהה הפוסט הבודד שלה בבקשה הבאה. אין פרמטר `limit` להגדלת המגבלה לכל בקשה.

## דפדוף ובקרת עלויות

`total` סופר את המערך המתאים בתגובה הנוכחית: פוסטים ברמה העליונה עבור שאילתות פוסטים, או תגובות בתוך כל רשומת תוצאה עבור שאילתות תגובות. זה אינו סך התאמות גלובלי, מספר התגובות המלא של פוסט, או מספר החיוב הסופי.

1. שלחו את הבקשה הראשונה ללא `cursor`.
2. קראו `has_next` ו-`next_cursor` מהתגובה. עבור תגובות, קראו אותם בכל רשומת תוצאה.
3. אם קיימת עמודה נוספת וה-cursor אינו ריק, שלחו אותו ללא שינוי עם אותה שאילתה. עבור אצוות תגובות, המשיכו כל פוסט בנפרד.
4. עצרו כאשר אין עמוד הבא, כאשר cursor חוזר על עצמו, או כאשר הגעתם למגבלת העמודים או ההוצאה שלכם.

מטא-נתוני הדפדוף משקפים את תגובת ה-upstream האחרונה; האוסף המוחזר יכול להיות מקוצר במגבלת תוצאות. אפילו `has_next=false` אינו הבטחה שכל היסטוריית X או כל התגובות אוחזרו. הציגו את הכמות שהוחזרה בפועל במקום לתייג קבוצת תוצאות מוגבלת ככול הנתונים הזמינים.

כל עמוד מוצלח יכול לגרור חיוב. חמש הפעולות הללו מחויבות לפי תוצאות שהוחזרו, לא לפי תשלום קבוע על בקשה. תגובות מקוננות ורשומות מוחזרות אחרות יכולות להשפיע על הכמות המחויבת; אל תעריכו עלות רק לפי אורך המערך ברמה העליונה. בדקו [מחירים נוכחיים](https://openapi.felo.ai/api/v1/data/prices) ואת השימוש בקונסול. שדות האובייקט המלאים נמצאים ב-[סכימת OpenAPI](https://openapi.felo.ai/api/v1/data/openapi.json).