# Data X

Dapatkan semula profil X, cari pengguna dan catatan, dan paginasi garis masa serta balasan.

Pilih operasi untuk data yang anda perlukan. Semua lima titik akhir menggunakan POST dan memulangkan JSON pada akar, tanpa pembungkus `data` yang umum.

Semua contoh menggunakan `FELO_API_KEY` daripada [gambaran keseluruhan](https://openapi.felo.ai/ms/docs/data-api/guides/felo-overview.md). Panggilan menggunakan **baki platform**, bukan kredit Felo Pro. Contoh respons adalah ilustratif; kandungan langsung dan medan pilihan berbeza.

## Pilih operasi

| Keperluan | Titik akhir |
|---|---|
| Profil untuk nama pengguna yang diketahui | `POST /api/v1/data/x/user/info` |
| Cari pengguna melalui pertanyaan carian | `POST /api/v1/data/x/user/search` |
| Catatan daripada seorang pengguna | `POST /api/v1/data/x/user/tweets` |
| Catatan yang sepadan dengan pertanyaan | `POST /api/v1/data/x/tweet/search` |
| Balasan kepada catatan yang diketahui | `POST /api/v1/data/x/tweet/replies` |

## 1. Dapatkan profil pengguna

`POST /api/v1/data/x/user/info`

| Medan | Jenis | Diperlukan | Makna |
|---|---|---|---|
| `usernames` | tatasusunan string | Ya | 1–100 nama pengguna; hantar handle tanpa `@` |

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

Respons mengandungi `users` dan `total`. Setiap pengguna merangkumi `user_id`, `username` dan `display_name`; teks profil, kiraan pengikut, pengesahan dan metadata lain juga mungkin hadir. Satu kelompok boleh memulangkan lebih sedikit profil daripada yang diminta. Padankan mengikut nama pengguna atau ID, bukan mengikut kedudukan tatasusunan.

```json
{"users":[{"user_id":"example-user-id","username":"example","display_name":"Example"}],"total":1}
```

## 2. Cari pengguna

`POST /api/v1/data/x/user/search`

| Medan | Jenis | Diperlukan | Makna |
|---|---|---|---|
| `query` | string | Ya | 1–1,000 aksara |
| `cursor` | string | Tidak | Cursor paginasi, sehingga 4,000 aksara |

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

Respons mengandungi `users`, `total`, `has_next` dan `next_cursor`. Tiada parameter `limit` pada operasi ini.

```json
{"users":[],"total":0,"has_next":false,"next_cursor":null}
```

## 3. Dapatkan garis masa pengguna

`POST /api/v1/data/x/user/tweets`

| Medan | Jenis | Diperlukan | Makna |
|---|---|---|---|
| `username` | string | Satu pengecam diperlukan | Handle pengguna, sehingga 100 aksara |
| `x_user_id` | string | Satu pengecam diperlukan | ID pengguna, sehingga 100 aksara; diutamakan berbanding `username` |
| `limit` | integer | Tidak | 1–1,000; pelaksanaan semasa menggunakan sekurang-kurangnya 20, dengan lalai 20 |
| `cursor` | string | Tidak | Cursor paginasi, sehingga 4,000 aksara |
| `include_replies` | boolean | Tidak | Sertakan balasan bersarang; lalai `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}'
```

Respons mengandungi `tweets`, `total`, `has_next` dan `next_cursor`. Menetapkan `limit` di bawah 20 tidak menjamin item yang dipulangkan lebih sedikit atau bil yang lebih kecil. Menyertakan balasan boleh menambah data yang dipulangkan dan hasil yang boleh dibilkan.

### Had hasil dan balasan bersarang

`limit` ialah bilangan sasaran catatan aras atas untuk permintaan ini, bukan kiraan hasil yang dijamin. Pelaksanaan semasa menggunakan sasaran sekurang-kurangnya 20: sasaran 20 membaca satu halaman huluan; sasaran yang lebih besar secara automatik mengambil sehingga 50 halaman. Sebelum setiap halaman, ia menyemak masa berlalu dan berhenti mengambil halaman seterusnya apabila ia melebihi 60 saat. Semakan ini bukan jaminan bahawa keseluruhan permintaan HTTP selesai dalam 60 saat.

Pengumpulan juga berhenti apabila sasaran dicapai, huluan tiada halaman seterusnya, halaman kosong, atau cursor hilang. Respons berjaya oleh itu boleh mengandungi lebih sedikit catatan daripada `limit`. Gunakan `has_next` dan `next_cursor` untuk meneruskan apabila tersedia.

Dengan `include_replies=true`, setiap catatan yang dipulangkan mendapat sehingga 5 halaman tambahan dan paling banyak 100 balasan bersarang. Pengumpulan boleh berhenti lebih awal apabila tiada halaman seterusnya, halaman kosong, atau cursor tidak boleh bergerak. Balasan bersarang ini berada di luar `limit` dan `total` aras atas, tetapi boleh menambah hasil yang boleh dibilkan.

Balasan bersarang `replies` bukan arkib balasan yang lengkap dan tidak mendedahkan cursor penerusan berasingan untuk pengumpulan tambahan ini. Untuk paginasi balasan secara bebas, gunakan operasi Baca balasan dan cursor yang dipulangkan. Jangan guna semula cursor catatan aras atas untuk balasan.

## 4. Cari catatan

`POST /api/v1/data/x/tweet/search`

| Medan | Jenis | Diperlukan | Makna |
|---|---|---|---|
| `query` | string | Ya | Teks carian, 1–1,000 aksara |
| `query_type` | string | Tidak | `Latest` (lalai) atau `Top` |
| `limit` | integer | Tidak | 1–1,000; pelaksanaan semasa menggunakan sekurang-kurangnya 20, dengan lalai 20 |
| `cursor` | string | Tidak | Cursor paginasi, sehingga 4,000 aksara |
| `since_time` | integer or string | Tidak | Masa mula; gunakan saat Unix untuk nilai angka yang tidak samar |
| `until_time` | integer or string | Tidak | Masa tamat; gunakan saat Unix, bukan milisaat |

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

Respons mengandungi `tweets`, `total`, `has_next` dan `next_cursor`. Objek catatan merangkumi `id`, `content`, `author`, `created_at` dan `metrics`; balasan dan catatan petikan/ulang siar mungkin bersarang. Perlakukan ID sebagai string.

### Had kiraan hasil

`limit` ialah sasaran, bukan jaminan. Pelaksanaan semasa menggunakan sasaran sekurang-kurangnya 20: sasaran 20 membaca satu halaman huluan; sasaran yang lebih besar secara automatik mengambil sehingga 50 halaman. Masa berlalu disemak sebelum setiap halaman, dan tiada halaman lanjut diambil sebaik sahaja ia melebihi 60 saat. Permintaan huluan yang sedang berjalan masih boleh mengambil masa, jadi ini bukan tamat masa HTTP keseluruhan.

Pengumpulan juga berhenti apabila sasaran dicapai, huluan tiada halaman seterusnya, halaman kosong, atau cursor hilang. Memulangkan lebih sedikit catatan daripada `limit` tidak bermaksud permintaan gagal atau bahawa setiap catatan padanan telah diambil. Semak `has_next` dan `next_cursor` sebelum meneruskan.

```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. Baca balasan

`POST /api/v1/data/x/tweet/replies`

| Medan | Jenis | Diperlukan | Makna |
|---|---|---|---|
| `tweet_ids` | string or string array | Ya | Satu ID catatan atau kelompok sehingga 20 ID |
| `cursor` | string | Tidak | Sehingga 4,000 aksara; gunakan dengan satu ID catatan |
| `since_time` | integer | Tidak | Masa mula dalam saat Unix |
| `until_time` | integer | Tidak | Masa tamat dalam saat Unix |

Gantikan ruang letak dengan ID catatan sebenar:

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

Tidak seperti garis masa dan carian catatan, balasan dikumpulkan di bawah `results`. Setiap entri mempunyai keadaan paginasi sendiri:

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

### Had balasan bagi setiap permintaan

Setiap permintaan membaca satu halaman balasan huluan bagi setiap `tweet_id` dan mengekalkan paling banyak 100 balasan; ia tidak secara automatik mengambil setiap halaman balasan. Dalam kelompok sehingga 20 ID, had 100 balasan terpakai secara berasingan pada setiap entri `results`. Kiraan sebenar boleh jadi lebih rendah.

`total` bagi setiap entri ialah bilangan balasan yang dipulangkan dalam entri itu, bukan kiraan balasan lengkap catatan tersebut. Untuk meneruskan, gunakan `next_cursor` bagi entri itu dan hantar hanya satu ID catatan tunggalnya dalam permintaan seterusnya. Tiada parameter `limit` untuk menambah had bagi setiap permintaan.

## Paginasi dan kawalan kos

`total` mengira tatasusunan yang sepadan dalam respons semasa: catatan aras atas untuk pertanyaan catatan, atau balasan dalam setiap entri hasil untuk pertanyaan balasan. Ia bukan kiraan padanan global, bukan kiraan balasan lengkap catatan, dan bukan kiraan boleh dibilkan akhir.

1. Hantar permintaan pertama tanpa `cursor`.
2. Baca `has_next` dan `next_cursor` daripada respons. Untuk balasan, baca pada setiap entri hasil.
3. Jika ada halaman lain dan cursor tidak kosong, hantar semula tanpa perubahan dengan pertanyaan yang sama. Untuk kelompok balasan, teruskan setiap catatan secara berasingan.
4. Berhenti apabila tiada halaman seterusnya, apabila cursor berulang, atau apabila had halaman atau perbelanjaan anda dicapai.

Metadata paginasi mencerminkan respons huluan terakhir; koleksi yang dipulangkan boleh dipotong pada had hasil. Malah `has_next=false` bukan jaminan bahawa semua sejarah X atau balasan telah diambil. Paparkan kiraan sebenar yang dipulangkan dan bukannya melabelkan set hasil terhad sebagai semua data yang tersedia.

Setiap halaman berjaya boleh menanggung caj. Lima operasi ini dibilkan mengikut hasil yang dipulangkan, bukan yuran permintaan tetap. Balasan bersarang dan rekod lain yang dipulangkan boleh mempengaruhi kiraan yang dibilkan; jangan anggarkan kos semata-mata berdasarkan panjang tatasusunan aras atas. Semak [harga semasa](https://openapi.felo.ai/api/v1/data/prices) dan penggunaan dalam konsol. Medan objek lengkap ada dalam [skema OpenAPI](https://openapi.felo.ai/api/v1/data/openapi.json).