# X ডেটা

X প্রোফাইল আহরণ করুন, ব্যবহারকারী ও পোস্ট খুঁজুন, এবং টাইমলাইন ও উত্তরের পেজিনেশন করুন।

আপনার প্রয়োজনীয় ডেটার জন্য উপযুক্ত operation বেছে নিন। পাঁচটি endpoint-ই POST ব্যবহার করে এবং কোনো common `data` wrapper ছাড়া root-এ JSON ফেরত দেয়।

সব example-ই [overview](https://openapi.felo.ai/bn/docs/data-api/guides/felo-overview.md) থেকে `FELO_API_KEY` ব্যবহার করে। Call-গুলো **platform balance** ব্যবহার করে, Felo Pro credits নয়। Response example-গুলো illustrative; live content এবং optional field ভিন্ন হতে পারে।

## একটি কার্যক্রম বেছে নিন

| প্রয়োজন | এন্ডপয়েন্ট |
| --- | --- |
| জানা ব্যবহারকারীনামের জন্য প্রোফাইল | `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 count, verification এবং অন্যান্য metadata-ও থাকতে পারে। একটি batch requested সংখ্যার চেয়ে কম profile ফেরত দিতে পারে। Array position নয়, username বা ID দিয়ে match করুন।

```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 | একটি পরিচায়ক প্রয়োজন | ব্যবহারকারী পরিচায়ক, সর্বোচ্চ 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-এর নিচে সেট করলে কম item ফেরত আসবে বা bill কম হবে—এমন নিশ্চয়তা নেই। Reply অন্তর্ভুক্ত করলে ফেরত আসা data এবং billable result বাড়তে পারে।

### ফলাফল এবং নেস্টেড উত্তরসীমা

`limit` হলো এই request-এর top-level post-এর লক্ষ্য সংখ্যা, guaranteed result count নয়। বর্তমান implementation কমপক্ষে 20-এর target ব্যবহার করে: 20-এর target একটি upstream page পড়ে; বড় target-এ স্বয়ংক্রিয়ভাবে সর্বোচ্চ 50 page fetch করে। প্রতিটি page-এর আগে elapsed time পরীক্ষা করা হয় এবং 60 second অতিক্রম করলে আরও page fetch বন্ধ হয়। এই পরীক্ষা পুরো HTTP request 60 second-এর মধ্যে শেষ হবে—এমন নিশ্চয়তা নয়।

Target পূরণ হলে, upstream-এ next page না থাকলে, একটি page ফাঁকা হলে, বা cursor অনুপস্থিত থাকলে collection-ও থেমে যায়। তাই একটি successful response-এ `limit`-এর চেয়ে কম post থাকতে পারে। উপলভ্য হলে চালিয়ে যেতে `has_next` এবং `next_cursor` ব্যবহার করুন।

`include_replies=true` হলে, প্রতিটি ফেরত আসা post-এর জন্য সর্বোচ্চ 5টি অতিরিক্ত page এবং সর্বাধিক 100টি nested reply যোগ হয়। Next page না থাকলে, page ফাঁকা হলে, বা cursor অগ্রসর হতে না পারলে collection আরও আগে বন্ধ হতে পারে। এই nested reply-গুলো top-level `limit` এবং `total`-এর বাইরে, কিন্তু billable result বাড়াতে পারে।

Nested `replies` সম্পূর্ণ reply archive নয় এবং এই অতিরিক্ত collection-এর জন্য আলাদা continuation cursor প্রকাশ করে না। স্বাধীনভাবে reply paginate করতে Read replies operation এবং এর ফেরত দেওয়া cursor ব্যবহার করুন। Reply-র জন্য 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 object-এ `id`, `content`, `author`, `created_at` এবং `metrics` থাকে; reply এবং quoted/retweeted post nested থাকতে পারে। ID-গুলোকে string হিসেবে বিবেচনা করুন।

### ফলাফলের সংখ্যা সীমা

`limit` একটি target, guarantee নয়। বর্তমান implementation কমপক্ষে 20-এর target ব্যবহার করে: 20-এর target একটি upstream page পড়ে; বড় target-এ স্বয়ংক্রিয়ভাবে সর্বোচ্চ 50 page fetch করে। প্রতিটি page-এর আগে elapsed time পরীক্ষা করা হয়, এবং 60 second অতিক্রম করলে আর কোনো page fetch করা হয় না। চলমান upstream request এখনও সময় নিতে পারে, তাই এটি সামগ্রিক HTTP timeout নয়।

Target পূরণ হলে, upstream-এ next page না থাকলে, page ফাঁকা হলে, বা cursor অনুপস্থিত থাকলে collection-ও থেমে যায়। `limit`-এর চেয়ে কম post ফেরত আসা মানে 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` | স্ট্রিং অথবা স্ট্রিং অ্যারে | হ্যাঁ | একটি পোস্ট পরিচায়ক অথবা সর্বোচ্চ 20টি পরিচায়কের ব্যাচ |
| `cursor` | string | না | সর্বোচ্চ 4,000 অক্ষর; একটি পোস্ট পরিচায়কের সাথে ব্যবহার করুন |
| `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-এর বিপরীতে, reply-গুলো `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টি reply ধরে রাখে; এটি স্বয়ংক্রিয়ভাবে প্রতিটি reply page fetch করে না। সর্বোচ্চ 20টি ID-এর একটি batch-এ, 100-reply cap প্রতিটি `results` entry-র জন্য আলাদাভাবে প্রযোজ্য। প্রকৃত সংখ্যা কম হতে পারে।

প্রতিটি entry-র `total` হলো ঐ entry-তে ফেরত আসা reply-এর সংখ্যা, post-এর সম্পূর্ণ reply count নয়। চালিয়ে যেতে, ঐ entry-র `next_cursor` ব্যবহার করুন এবং পরবর্তী request-এ কেবল তার একক post ID পাঠান। প্রতি-request cap বাড়ানোর জন্য কোনো `limit` parameter নেই।

## পেজিনেশন এবং খরচ নিয়ন্ত্রণ

`total` বর্তমান response-এর সংশ্লিষ্ট array গণনা করে: post query-র জন্য top-level post, অথবা reply query-র জন্য প্রতিটি result entry-র মধ্যে reply। এটি global match count, কোনো post-এর সম্পূর্ণ reply count, বা চূড়ান্ত billable count নয়।

1. `cursor` ছাড়া প্রথম request পাঠান।
2. Response থেকে `has_next` এবং `next_cursor` পড়ুন। Reply-এর ক্ষেত্রে, প্রতিটি result entry-তে এগুলো পড়ুন।
3. যদি আরেকটি page থাকে এবং cursor খালি না হয়, একই query-সহ অপরিবর্তিত অবস্থায় তা পাঠান। Reply batch-এর জন্য, প্রতিটি post আলাদাভাবে চালিয়ে যান।
4. Next page না থাকলে, cursor পুনরাবৃত্ত হলে, বা আপনার নিজস্ব page বা spending limit-এ পৌঁছালে থামুন।

Pagination metadata শেষ upstream response প্রতিফলিত করে; ফেরত আসা collection result cap-এ truncate হতে পারে। এমনকি `has_next=false`-ও সব X history বা reply আহরণ হয়েছে—এমন নিশ্চয়তা নয়। সীমাবদ্ধ result set-কে all available data বলে label না করে প্রকৃত ফেরত আসা count প্রদর্শন করুন।

প্রতিটি successful page-এ চার্জ হতে পারে। এই পাঁচটি operation flat request fee নয়, ফেরত আসা result অনুযায়ী বিল হয়। Nested reply এবং অন্যান্য ফেরত আসা record bill করা count-এ প্রভাব ফেলতে পারে; কেবল top-level array length থেকে খরচ অনুমান করবেন না। [current prices](https://openapi.felo.ai/api/v1/data/prices) এবং console-এ usage পরীক্ষা করুন। সম্পূর্ণ object field [OpenAPI schema](https://openapi.felo.ai/api/v1/data/openapi.json)-এ রয়েছে।