# X ڈیٹا

X پروفائلز حاصل کریں، صارفین اور پوسٹس تلاش کریں، اور timelines اور replies میں pagination کریں۔

جس data کی آپ کو ضرورت ہے، اس کے مطابق operation منتخب کریں۔ پانچوں endpoints POST استعمال کرتے ہیں اور root پر JSON واپس کرتے ہیں، کسی مشترک `data` wrapper کے بغیر۔

تمام examples، [overview](https://openapi.felo.ai/ur/docs/data-api/guides/felo-overview.md) سے `FELO_API_KEY` استعمال کرتے ہیں۔ Calls **platform balance** استعمال کرتی ہیں، Felo Pro credits نہیں۔ Response examples صرف وضاحتی ہیں؛ live content اور optional fields مختلف ہو سکتے ہیں۔

## ایک کارروائی منتخب کریں

| ضرورت | نقطۂ اختتام |
| --- | --- |
| معلوم صارف ناموں کے لیے پروفائلز | `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` | سٹرنگ ارے | ہاں | 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"]}'
```

Response میں `users` اور `total` شامل ہوتے ہیں۔ ہر user میں `user_id`، `username` اور `display_name` شامل ہوتا ہے؛ profile text، follower counts، verification اور دوسری metadata بھی موجود ہو سکتی ہے۔ ایک batch، requested profiles سے کم profiles واپس کر سکتا ہے۔ username یا ID کے مطابق match کریں، array position کے مطابق نہیں۔

```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"}'
```

Response میں `users`، `total`، `has_next` اور `next_cursor` شامل ہوتے ہیں۔ اس operation میں `limit` parameter نہیں ہے۔

```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 | ایک شناخت کنندہ درکار ہے | صارف ID، 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}'
```

Response میں `tweets`، `total`، `has_next` اور `next_cursor` شامل ہوتے ہیں۔ `limit` کو 20 سے کم سیٹ کرنے سے کم returned items یا کم بل کی ضمانت نہیں ملتی۔ replies شامل کرنے سے returned data اور billable results بڑھ سکتے ہیں۔

### نتیجے اور گھریلو جواب کی حدود

`limit` اس request کے لیے top-level posts کی target تعداد ہے، guaranteed result count نہیں۔ موجودہ implementation کم از کم 20 کی target استعمال کرتی ہے: 20 کی target ایک upstream page پڑھتی ہے؛ بڑی targets خودکار طور پر 50 pages تک fetch کرتی ہیں۔ ہر page سے پہلے، یہ elapsed time چیک کرتی ہے اور جب یہ 60 seconds سے تجاوز کر جائے تو مزید pages fetch کرنا بند کر دیتی ہے۔ یہ چیک اس بات کی ضمانت نہیں کہ پوری HTTP request 60 seconds کے اندر مکمل ہو گی۔

Collection اس وقت بھی رک جاتی ہے جب target پوری ہو جائے، upstream کے پاس اگلا page نہ ہو، کوئی page خالی ہو، یا cursor موجود نہ ہو۔ اس لیے successful response میں `limit` سے کم posts ہو سکتی ہیں۔ جہاں دستیاب ہو، جاری رکھنے کے لیے `has_next` اور `next_cursor` استعمال کریں۔

`include_replies=true` کے ساتھ، ہر returned post کو 5 اضافی pages تک اور زیادہ سے زیادہ 100 nested replies ملتی ہیں۔ Collection اس سے پہلے بھی رک سکتی ہے اگر اگلا page نہ ہو، page خالی ہو، یا cursor آگے نہ بڑھ سکے۔ یہ nested replies top-level `limit` اور `total` سے باہر ہوتی ہیں، لیکن billable results میں اضافہ کر سکتی ہیں۔

Nested `replies` مکمل reply archive نہیں ہیں اور اس اضافی collection کے لیے الگ continuation cursor ظاہر نہیں کرتیں۔ replies کو آزادانہ paginate کرنے کے لیے، Read replies operation اور اس کے returned cursor کو استعمال کریں۔ replies کے لیے top-level post 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 | نہیں | صفحہ بندی کا کرسر، 4,000 حروف تک |
| `since_time` | عدد یا سٹرنگ | نہیں | آغاز وقت؛ غیر مبہم عددی قدر کے لیے Unix سیکنڈز استعمال کریں |
| `until_time` | عدد یا سٹرنگ | نہیں | اختتام وقت؛ 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}'
```

Response میں `tweets`، `total`، `has_next` اور `next_cursor` شامل ہوتے ہیں۔ Post objects میں `id`، `content`، `author`، `created_at` اور `metrics` شامل ہوتے ہیں؛ replies اور quoted/retweeted posts nested ہو سکتی ہیں۔ IDs کو strings کے طور پر treat کریں۔

### نتیجے کی تعداد کی حدود

`limit` ایک target ہے، guarantee نہیں۔ موجودہ implementation کم از کم 20 کی target استعمال کرتی ہے: 20 کی target ایک upstream page پڑھتی ہے؛ بڑی targets خودکار طور پر 50 pages تک fetch کرتی ہیں۔ ہر page سے پہلے elapsed time چیک کیا جاتا ہے، اور 60 seconds سے تجاوز کے بعد مزید pages fetch نہیں کیے جاتے۔ ایک جاری upstream request پھر بھی وقت لے سکتی ہے، اس لیے یہ مجموعی HTTP timeout نہیں ہے۔

Collection اس وقت بھی رک جاتی ہے جب target پوری ہو جائے، upstream کے پاس اگلا page نہ ہو، کوئی page خالی ہو، یا cursor موجود نہ ہو۔ `limit` سے کم posts واپس آنے کا مطلب یہ نہیں کہ request ناکام ہوئی یا ہر matching post حاصل کر لی گئی۔ آگے بڑھنے سے پہلے `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` | سٹرنگ یا سٹرنگ ارے | ہاں | ایک پوسٹ ID یا زیادہ سے زیادہ 20 IDs کا بیچ |
| `cursor` | string | نہیں | 4,000 حروف تک؛ ایک پوسٹ ID کے ساتھ استعمال کریں |
| `since_time` | integer | نہیں | Unix سیکنڈز میں آغاز وقت |
| `until_time` | integer | نہیں | Unix سیکنڈز میں اختتام وقت |

placeholder کو ایک حقیقی post ID سے بدلیں:

```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"]}'
```

Timeline اور post search کے برعکس، replies `results` کے تحت group ہوتی ہیں۔ ہر entry کی اپنی pagination state ہوتی ہے:

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

### درخواست کے فی جواب حدود

ہر request، فی `tweet_id` ایک upstream reply page پڑھتی ہے اور زیادہ سے زیادہ 100 replies رکھتی ہے؛ یہ خودکار طور پر ہر reply page fetch نہیں کرتی۔ زیادہ سے زیادہ 20 IDs کے batch میں، 100-reply cap ہر `results` entry پر الگ سے لاگو ہوتی ہے۔ اصل counts اس سے کم ہو سکتی ہیں۔

ہر entry کا `total` اس entry میں واپس آنے والی replies کی تعداد ہے، post کے مکمل reply count کی نہیں۔ جاری رکھنے کے لیے، اس entry کا `next_cursor` استعمال کریں اور اگلی request میں صرف اسی ایک post ID کو بھیجیں۔ فی request cap بڑھانے کے لیے کوئی `limit` parameter موجود نہیں۔

## صفحہ بندی اور لاگت کا نظم

`total` موجودہ response میں متعلقہ array کو شمار کرتا ہے: post queries کے لیے top-level posts، یا reply queries کے لیے ہر result entry کے اندر replies۔ یہ global match count، کسی post کے مکمل reply count، یا آخری billable count نہیں ہے۔

1. پہلی request `cursor` کے بغیر بھیجیں۔
2. Response سے `has_next` اور `next_cursor` پڑھیں۔ replies کے لیے، ہر result entry پر انہیں پڑھیں۔
3. اگر دوسرا page موجود ہو اور cursor خالی نہ ہو، تو اسی query کے ساتھ اسے بغیر تبدیلی کے بھیجیں۔ replies batch کے لیے، ہر post کو الگ الگ جاری رکھیں۔
4. جب اگلا page نہ ہو، cursor دوبارہ آنے لگے، یا آپ کی اپنی page یا spending limit پوری ہو جائے، تو رک جائیں۔

Pagination metadata آخری upstream response کو ظاہر کرتی ہے؛ returned collection کو result cap پر truncate کیا جا سکتا ہے۔ حتیٰ کہ `has_next=false` بھی اس بات کی guarantee نہیں کہ تمام X history یا replies حاصل کر لی گئی ہیں۔ bounded result set کو تمام دستیاب data کہنے کے بجائے اصل returned count دکھائیں۔

ہر successful page charge پیدا کر سکتا ہے۔ یہ پانچ operations flat request fee کے بجائے returned results کے مطابق بل کیے جاتے ہیں۔ Nested replies اور دیگر returned records billable count پر اثر ڈال سکتے ہیں؛ صرف top-level array length سے cost کا اندازہ نہ لگائیں۔ [current prices](https://openapi.felo.ai/api/v1/data/prices) اور console میں usage چیک کریں۔ مکمل object fields [OpenAPI schema](https://openapi.felo.ai/api/v1/data/openapi.json) میں موجود ہیں۔