# X डेटा

X प्रोफ़ाइल प्राप्त करें, उपयोगकर्ता और पोस्ट खोजें, और timeline तथा replies को paginate करें।

आपको जिस डेटा की आवश्यकता है, उसके लिए उपयुक्त operation चुनें। सभी पाँच endpoints POST का उपयोग करते हैं और root पर JSON लौटाते हैं, बिना किसी shared `data` wrapper के।

सभी examples [overview](https://openapi.felo.ai/hi/docs/data-api/guides/felo-overview.md) से `FELO_API_KEY` का उपयोग करते हैं। Calls **platform balance** का उपयोग करती हैं, Felo Pro credits का नहीं। Response examples केवल illustrative हैं; 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 request किए गए profiles से कम profiles लौटा सकता है। Match username या ID से करें, 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 या छोटे bill की गारंटी नहीं देता। 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 में next page न हो, कोई page empty हो, या cursor missing हो। इसलिए एक successful response में `limit` से कम posts हो सकती हैं। जहाँ उपलब्ध हो, जारी रखने के लिए `has_next` और `next_cursor` का उपयोग करें।

`include_replies=true` के साथ, प्रत्येक returned post को अधिकतम 5 extra pages और अधिकतम 100 nested replies मिलती हैं। Collection इससे पहले भी रुक सकती है जब next page न हो, page empty हो, या cursor आगे न बढ़ सके। ये nested replies top-level `limit` और `total` के बाहर हैं, लेकिन billable results बढ़ा सकती हैं।

Nested `replies` complete reply archive नहीं हैं और इस extra collection के लिए अलग continuation cursor उपलब्ध नहीं करातीं। Replies को independently 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 नहीं किए जाते। In-flight upstream request फिर भी समय ले सकती है, इसलिए यह overall HTTP timeout नहीं है।

Collection तब भी रुक जाती है जब target पूरा हो जाए, upstream में next page न हो, कोई page empty हो, या cursor missing हो। `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 पर अलग-अलग लागू होती है। Actual counts इससे कम हो सकते हैं।

प्रत्येक entry का `total` उस entry में लौटाई गई replies की संख्या है, post की complete reply count नहीं। जारी रखने के लिए, उस entry के `next_cursor` का उपयोग करें और अगली request में केवल उसी single post ID को भेजें। प्रति-request cap बढ़ाने के लिए कोई `limit` parameter नहीं है।

## पृष्ठांकन और लागत नियंत्रण

`total` वर्तमान response में संबंधित array को count करता है: post queries के लिए top-level posts, या reply queries के लिए प्रत्येक result entry के भीतर replies। यह global match count, किसी post की complete reply count, या अंतिम billable count नहीं है।

1. पहली request `cursor` के बिना भेजें।
2. Response से `has_next` और `next_cursor` पढ़ें। Replies के लिए, उन्हें प्रत्येक result entry पर पढ़ें।
3. यदि कोई और page मौजूद है और cursor nonempty है, तो उसी query के साथ उसे बिना बदले भेजें। Replies batch के लिए, प्रत्येक post को अलग-अलग जारी रखें।
4. जब next page न हो, cursor दोहराया जाए, या आपकी अपनी page अथवा spending limit पूरी हो जाए, तब रुकें।

Pagination metadata अंतिम upstream response को दर्शाती है; returned collection result cap पर truncate हो सकती है। यहाँ तक कि `has_next=false` भी इस बात की गारंटी नहीं है कि पूरा X history या replies प्राप्त कर लिए गए हैं। Bounded result set को all available data कहने के बजाय actual returned count दिखाएँ।

हर successful page पर charge लग सकता है। ये पाँच operations flat request fee से नहीं, बल्कि returned results के अनुसार billed होती हैं। Nested replies और अन्य returned records billed count को प्रभावित कर सकते हैं; केवल top-level array length से cost का अनुमान न लगाएँ। [current prices](https://openapi.felo.ai/api/v1/data/prices) और console में usage जाँचें। Complete object fields [OpenAPI schema](https://openapi.felo.ai/api/v1/data/openapi.json) में हैं।