# ข้อมูล X

ดึงโปรไฟล์ X ค้นหาผู้ใช้และโพสต์ และแบ่งหน้าของไทม์ไลน์และคำตอบ.

เลือกการทำงานให้ตรงกับข้อมูลที่คุณต้องการ ทั้งห้าเอนด์พอยต์ใช้ POST และส่งคืน JSON ที่ราก โดยไม่มี wrapper `data` ร่วมกัน

ตัวอย่างทั้งหมดใช้ `FELO_API_KEY` จาก [ภาพรวม](https://openapi.felo.ai/th/docs/data-api/guides/felo-overview.md) การเรียกใช้ใช้ **ยอดคงเหลือบนแพลตฟอร์ม** ไม่ใช่ Felo Pro credits ตัวอย่างการตอบกลับมีไว้เพื่อประกอบการอธิบาย; เนื้อหาจริงและฟิลด์เสริมอาจแตกต่างกัน

## เลือกการทำงาน

| สิ่งที่ต้องการ | เอนด์พอยต์ |
|---|---|
| โปรไฟล์สำหรับ username ที่ทราบ | `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 usernames; ส่ง handle โดยไม่ต้องมี `@` |

```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`; ข้อความโปรไฟล์ จำนวนผู้ติดตาม การยืนยันตัวตน และเมตาดาตาอื่นๆ อาจมีอยู่ด้วย ชุดคำขอหนึ่งครั้งอาจส่งคืนโปรไฟล์น้อยกว่าที่ร้องขอ จับคู่ด้วย username หรือ ID ไม่ใช่ตำแหน่งในอาร์เรย์

```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 | ต้องมีหนึ่งตัวระบุ | handle ของผู้ใช้, ยาวได้ถึง 100 อักขระ |
| `x_user_id` | string | ต้องมีหนึ่งตัวระบุ | ID ของผู้ใช้, ยาวได้ถึง 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 ไม่ได้ทำให้แน่ใจว่าจะมีรายการที่ส่งคืนลดลงหรือค่าบริการน้อยลง การรวม replies อาจเพิ่มข้อมูลที่ส่งคืนและผลลัพธ์ที่คิดค่าบริการได้

### ขีดจำกัดผลลัพธ์และคำตอบย่อยที่ซ้อนกัน

`limit` คือจำนวนเป้าหมายของโพสต์ระดับบนสำหรับคำขอนี้ ไม่ใช่จำนวนผลลัพธ์ที่รับประกัน การใช้งานปัจจุบันใช้เป้าหมายอย่างน้อย 20: เป้าหมาย 20 จะอ่าน upstream page หนึ่งหน้า; เป้าหมายที่มากกว่าจะดึงอัตโนมัติได้สูงสุด 50 หน้า ก่อนแต่ละหน้า จะตรวจสอบเวลาเริ่มต้นและหยุดดึงหน้าต่อไปเมื่อเกิน 60 วินาที การตรวจสอบนี้ไม่ได้รับประกันว่าคำขอ HTTP ทั้งหมดจะเสร็จภายใน 60 วินาที

การเก็บข้อมูลยังหยุดเมื่อถึงเป้าหมาย upstream ไม่มีหน้าถัดไป หน้าว่าง หรือ cursor หายไป ดังนั้นการตอบกลับที่สำเร็จอาจมีโพสต์น้อยกว่า `limit` ใช้ `has_next` และ `next_cursor` เพื่อดำเนินต่อเมื่อมีอยู่

เมื่อ `include_replies=true` แต่ละโพสต์ที่ส่งคืนจะได้หน้าพิเศษเพิ่มได้สูงสุด 5 หน้า และตอบกลับย่อยที่ซ้อนกันได้มากสุด 100 รายการ การเก็บข้อมูลอาจหยุดก่อนเมื่อไม่มีหน้าถัดไป หน้าว่าง หรือ cursor ไม่สามารถเดินต่อได้ ตอบกลับย่อยเหล่านี้อยู่นอก `limit` และ `total` ระดับบน แต่สามารถเพิ่มผลลัพธ์ที่คิดค่าบริการได้

`replies` ที่ซ้อนกันไม่ใช่คลังคำตอบที่ครบถ้วน และไม่เปิดเผย cursor การดำเนินต่อแยกต่างหากสำหรับการเก็บข้อมูลพิเศษนี้ หากต้องการแบ่งหน้าคำตอบแยกต่างหาก ให้ใช้การทำงาน Read replies และ cursor ที่ส่งคืนมา อย่านำ cursor ของโพสต์ระดับบนมาใช้ซ้ำกับ 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 | ไม่ | cursor สำหรับการแบ่งหน้า, ยาวได้ถึง 4,000 อักขระ |
| `since_time` | integer or string | ไม่ | เวลาเริ่มต้น; ใช้ Unix seconds เพื่อให้ค่าเป็นตัวเลขที่ชัดเจน |
| `until_time` | integer or string | ไม่ | เวลาสิ้นสุด; ใช้ Unix seconds ไม่ใช่ milliseconds |

```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`; replies และโพสต์ที่อ้างถึง/รีทวีตอาจซ้อนอยู่ Treat IDs as strings.

### ขีดจำกัดจำนวนผลลัพธ์

`limit` คือเป้าหมาย ไม่ใช่การรับประกัน การใช้งานปัจจุบันใช้เป้าหมายอย่างน้อย 20: เป้าหมาย 20 จะอ่าน upstream page หนึ่งหน้า; เป้าหมายที่มากกว่าจะดึงอัตโนมัติได้สูงสุด 50 หน้า เวลาเริ่มต้นจะถูกตรวจสอบก่อนแต่ละหน้า และจะไม่ดึงหน้าต่อไปเมื่อเกิน 60 วินาที upstream request ที่กำลังดำเนินการอยู่ยังอาจใช้เวลาได้ ดังนั้นนี่ไม่ใช่ overall HTTP timeout

การเก็บข้อมูลยังหยุดเมื่อถึงเป้าหมาย 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 | ใช่ | ID โพสต์หนึ่งรายการ หรือเป็นชุดสูงสุด 20 IDs |
| `cursor` | string | ไม่ | ยาวได้ถึง 4,000 อักขระ; ใช้กับ post ID เดียว |
| `since_time` | integer | ไม่ | เวลาเริ่มต้นใน Unix seconds |
| `until_time` | integer | ไม่ | เวลาสิ้นสุดใน Unix seconds |

แทนที่ 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"]}'
```

ต่างจากไทม์ไลน์และการค้นหาโพสต์ คำตอบจะถูกรวมอยู่ใต้ `results` แต่ละรายการมีสถานะการแบ่งหน้าของตนเอง:

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

### ขีดจำกัดคำตอบต่อคำขอ

แต่ละคำขออ่าน upstream reply page หนึ่งหน้าต่อ `tweet_id` และเก็บไว้ได้มากสุด 100 replies; มันไม่ได้ดึงทุก reply page โดยอัตโนมัติ ในชุดสูงสุด 20 IDs ขีดจำกัด 100 replies จะใช้แยกกันสำหรับแต่ละรายการ `results` จำนวนจริงอาจน้อยกว่านั้น

`total` ของแต่ละรายการคือจำนวน replies ที่ส่งคืนในรายการนั้น ไม่ใช่จำนวน replies ทั้งหมดของโพสต์ หากต้องการต่อ ให้ใช้ `next_cursor` ของรายการนั้นและส่งเฉพาะ post ID เดี่ยวของมันในคำขอถัดไป ไม่มีพารามิเตอร์ `limit` ที่เพิ่มขีดจำกัดต่อคำขอ

## การแบ่งหน้าและการควบคุมค่าใช้จ่าย

`total` นับอาร์เรย์ที่สอดคล้องกันใน response ปัจจุบัน: โพสต์ระดับบนสำหรับคำถามโพสต์ หรือ replies ภายในแต่ละรายการผลลัพธ์สำหรับคำถาม replies มันไม่ใช่จำนวนแมตช์ทั่วโลก จำนวน replies ทั้งหมดของโพสต์ หรือจำนวนที่คิดค่าบริการสุดท้าย

1. ส่งคำขอแรกโดยไม่ใส่ `cursor`.
2. อ่าน `has_next` และ `next_cursor` จาก response สำหรับ replies ให้อ่านในแต่ละรายการผลลัพธ์
3. หากมีหน้าถัดไปและ cursor ไม่ว่าง ให้ส่งค่าเดิมโดยไม่เปลี่ยนพร้อมกับคำค้นหาเดิม สำหรับชุด replies ให้ดำเนินต่อทีละโพสต์
4. หยุดเมื่อไม่มีหน้าถัดไป เมื่อ cursor ซ้ำ หรือเมื่อถึงขีดจำกัดหน้าหรือค่าใช้จ่ายของคุณ

เมตาดาตาการแบ่งหน้าสะท้อน response upstream ล่าสุด; collection ที่ส่งคืนอาจถูกตัดที่ขีดจำกัดผลลัพธ์ แม้แต่ `has_next=false` ก็ไม่รับประกันว่าประวัติ X หรือ replies ทั้งหมดถูกดึงแล้ว แสดงจำนวนที่ส่งคืนจริงแทนที่จะติดป้ายชุดผลลัพธ์ที่มีขอบเขตว่าเป็นข้อมูลทั้งหมดที่มีอยู่

แต่ละหน้าที่สำเร็จอาจมีค่าบริการได้ การทำงานทั้งห้านี้คิดค่าบริการตามผลลัพธ์ที่ส่งคืน ไม่ใช่ค่าธรรมเนียมต่อคำขอแบบคงที่ replies ที่ซ้อนกันและระเบียนที่ส่งคืนอื่นๆ อาจมีผลต่อจำนวนที่คิดค่าบริการ; อย่าประเมินต้นทุนจากความยาวของอาร์เรย์ระดับบนเพียงอย่างเดียว ตรวจสอบ [ราคาปัจจุบัน](https://openapi.felo.ai/api/v1/data/prices) และการใช้งานในคอนโซล ฟิลด์ออบเจ็กต์ฉบับสมบูรณ์อยู่ใน [OpenAPI schema](https://openapi.felo.ai/api/v1/data/openapi.json)