# X Search API

Tìm người dùng X, tweet, dòng thời gian và câu trả lời với siêu dữ liệu phân trang.

Trang này tài liệu hóa các Felo API `/v2` hiện có, sử dụng **quyền được cấp của tài khoản Felo và các quy tắc tín dụng Pro**. Việc tín dụng có bị trừ hay không phụ thuộc vào [thao tác](https://openapi.felo.ai/vi/docs/faq/billing-and-credits.md#quy-t-c-t-n-d-ng-theo-kh-n-ng-v2). Với các cuộc gọi dùng số dư nền tảng, hãy chọn một [endpoint Felo OpenAPI](https://openapi.felo.ai/vi/docs/api-reference/openapi/overview.md) được hỗ trợ; hình dạng yêu cầu và phản hồi có thể khác nhau.


X Search API cung cấp quyền truy cập vào dữ liệu X (Twitter), bao gồm hồ sơ người dùng, tìm kiếm tweet, tweet của người dùng và phản hồi tweet.

## Dùng với AI Agents

Cài toàn bộ gói `felo-ai` để cho một Agent dùng X Search và mọi Felo Skill khác đang có. Trình cài đặt sẽ tự động phát hiện mọi thư mục gói có chứa `SKILL.md`, thay vì giữ một danh sách Skill cố định. Cài tất cả các Skill được phát hiện trong Codex `~/.codex/skills`, Claude Code `~/.claude/skills`, OpenClaw `~/.agents/skills`, hoặc Hermes Agent `~/.hermes/skills`. Xem [hướng dẫn thiết lập AI Agent thủ công](https://openapi.felo.ai/vi/docs/felo-skills.md) để biết chỉ dẫn cài đặt, API key và xác minh dành riêng cho từng nền tảng.


## Xác thực

Tất cả yêu cầu đều cần API Key trong header `Authorization`:

```
Authorization: Bearer YOUR_API_KEY
```

---

## 1. Lấy thông tin người dùng

Truy xuất hàng loạt hồ sơ người dùng X theo username.

### Endpoint

```
POST https://openapi.felo.ai/v2/x/user/info
```

### Phần thân yêu cầu

| Tham số | Kiểu | Bắt buộc | Mô tả |
|-----------|------|----------|-------------|
| `usernames` | mảng chuỗi | Có | Danh sách các username X cần tra cứu |

### Ví dụ

```bash
curl -X POST 'https://openapi.felo.ai/v2/x/user/info' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "usernames": ["elonmusk", "OpenAI"]
  }'
```

### Phản hồi thành công (200)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "message": null,
  "data": {
    "total": 2,
    "users": [
      {
        "user_id": "44196397",
        "username": "elonmusk",
        "display_name": "Elon Musk",
        "description": "...",
        "followers_count": 100000000,
        "following_count": 500,
        "tweet_count": 30000,
        "verified": true,
        "blue_verified": true,
        "profile_image_url": "https://pbs.twimg.com/...",
        "created_at": "2009-06-02T00:00:00Z",
        "location": "Mars"
      }
    ]
  }
}
```

### Trường đối tượng người dùng

| Trường | Kiểu | Mô tả |
|-------|------|-------------|
| `user_id` | string | ID người dùng X |
| `username` | string | Handle X (không có @) |
| `display_name` | string | Tên hiển thị |
| `description` | string | Tiểu sử người dùng |
| `followers_count` | integer | Số người theo dõi |
| `following_count` | integer | Số tài khoản đang theo dõi |
| `tweet_count` | integer | Tổng số tweet |
| `verified` | boolean | Tài khoản có được xác minh hay không |
| `blue_verified` | boolean | Tài khoản có xác minh Blue hay không |
| `verified_type` | string | Loại xác minh |
| `profile_image_url` | string | URL ảnh đại diện |
| `cover_image_url` | string | URL ảnh bìa |
| `created_at` | string | Thời điểm tạo tài khoản |
| `location` | string | Vị trí người dùng |
| `url` | string | URL trang web của người dùng |
| `protected` | boolean | Tài khoản có được bảo vệ hay không |
| `favorites_count` | integer | Số lượt thích |
| `media_count` | integer | Số bài đăng có media |
| `can_dm` | boolean | DM có mở hay không |
| `is_automated` | boolean | Tài khoản có tự động hóa hay không |
| `pinned_tweet_ids` | mảng chuỗi | ID tweet được ghim |

---

## 2. Tìm kiếm người dùng

Tìm kiếm người dùng X theo từ khóa.

### Endpoint

```
POST https://openapi.felo.ai/v2/x/user/search
```

### Phần thân yêu cầu

| Tham số | Kiểu | Bắt buộc | Mô tả |
|-----------|------|----------|-------------|
| `query` | string | Có | Từ khóa tìm kiếm |
| `cursor` | string | Không | Con trỏ phân trang từ phản hồi trước |

### Ví dụ

```bash
curl -X POST 'https://openapi.felo.ai/v2/x/user/search' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "artificial intelligence"
  }'
```

### Phản hồi thành công (200)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "message": null,
  "data": {
    "total": 50,
    "has_next": true,
    "next_cursor": "cursor_abc123",
    "users": [
      {
        "user_id": "...",
        "username": "...",
        "display_name": "..."
      }
    ]
  }
}
```

### Trường phản hồi

| Trường | Kiểu | Mô tả |
|-------|------|-------------|
| `total` | integer | Tổng số kết quả |
| `has_next` | boolean | Có thêm kết quả hay không |
| `next_cursor` | string | Con trỏ cho trang tiếp theo |
| `users` | array | Danh sách đối tượng người dùng (xem mục 1) |

---

## 3. Lấy tweet của người dùng

Truy xuất các tweet từ một người dùng X cụ thể.

### Endpoint

```
POST https://openapi.felo.ai/v2/x/user/tweets
```

### Phần thân yêu cầu

| Tham số | Kiểu | Bắt buộc | Mô tả |
|-----------|------|----------|-------------|
| `x_user_id` | string | Không | ID người dùng X (cung cấp либо `x_user_id` hoặc `username`) |
| `username` | string | Không | Username X (cung cấp либо `x_user_id` hoặc `username`) |
| `limit` | integer | Không | Số tweet cần trả về |
| `cursor` | string | Không | Con trỏ phân trang |
| `include_replies` | boolean | Không | Có bao gồm phản hồi hay không |

### Ví dụ

```bash
curl -X POST 'https://openapi.felo.ai/v2/x/user/tweets' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "elonmusk",
    "limit": 20
  }'
```

### Phản hồi thành công (200)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "message": null,
  "data": {
    "total": 20,
    "has_next": true,
    "next_cursor": "cursor_def456",
    "tweets": [
      {
        "id": "1234567890",
        "content": "Tweet content here...",
        "author": { "user_id": "...", "username": "elonmusk" },
        "created_at": "2026-03-09T12:00:00Z",
        "metrics": {
          "retweet_count": 1000,
          "favorite_count": 5000,
          "reply_count": 200,
          "quote_count": 100,
          "view_count": 500000,
          "bookmark_count": 50
        },
        "hashtags": ["AI"],
        "mentions": ["OpenAI"],
        "url": "https://x.com/elonmusk/status/1234567890",
        "lang": "en"
      }
    ]
  }
}
```

### Trường đối tượng tweet

| Trường | Kiểu | Mô tả |
|-------|------|-------------|
| `id` | string | ID tweet |
| `content` | string | Nội dung văn bản tweet |
| `author` | object | Đối tượng người dùng tác giả (xem mục 1) |
| `created_at` | string | Thời điểm tạo tweet |
| `metrics` | object | Chỉ số tương tác (xem bên dưới) |
| `replies` | array | Các tweet phản hồi (nếu có) |
| `conversation_id` | string | ID luồng hội thoại |
| `media_urls` | array | Media đính kèm |
| `hashtags` | array of strings | Hashtag trong tweet |
| `mentions` | array of strings | Các username được nhắc tới |
| `urls` | array of strings | URL trong tweet |
| `url` | string | Permalink tới tweet |
| `source` | string | Nguồn tweet (ví dụ "Twitter Web App") |
| `lang` | string | Mã ngôn ngữ của tweet |
| `is_reply` | boolean | Đây có phải phản hồi hay không |
| `in_reply_to_id` | string | ID của tweet được phản hồi |
| `in_reply_to_user_id` | string | ID người dùng của tweet được phản hồi |
| `in_reply_to_username` | string | Username của tweet được phản hồi |
| `quoted_tweet` | object | Đối tượng tweet được trích dẫn (đệ quy) |
| `retweeted_tweet` | object | Đối tượng tweet được đăng lại (đệ quy) |
| `is_limited_reply` | boolean | Phản hồi có bị giới hạn hay không |

### Trường đối tượng metrics

| Trường | Kiểu | Mô tả |
|-------|------|-------------|
| `retweet_count` | integer | Số lần đăng lại |
| `favorite_count` | integer | Số lượt thích |
| `reply_count` | integer | Số phản hồi |
| `quote_count` | integer | Số lần trích dẫn |
| `view_count` | integer | Số lượt xem |
| `bookmark_count` | integer | Số lượt lưu trang |

---

## 4. Tìm kiếm tweet

Tìm kiếm tweet X theo từ khóa với hỗ trợ truy vấn nâng cao.

### Endpoint

```
POST https://openapi.felo.ai/v2/x/tweet/search
```

### Phần thân yêu cầu

| Tham số | Kiểu | Bắt buộc | Mô tả |
|-----------|------|----------|-------------|
| `query` | string | Có | Truy vấn tìm kiếm (hỗ trợ cú pháp tìm kiếm nâng cao) |
| `query_type` | string | Không | Bộ lọc loại truy vấn |
| `since_time` | integer | Không | Bộ lọc thời gian bắt đầu (dấu thời gian Unix tính bằng giây) |
| `until_time` | integer | Không | Bộ lọc thời gian kết thúc (dấu thời gian Unix tính bằng giây) |
| `limit` | integer | Không | Số tweet cần trả về |
| `cursor` | string | Không | Con trỏ phân trang |

### Ví dụ

```bash
curl -X POST 'https://openapi.felo.ai/v2/x/tweet/search' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "artificial intelligence",
    "limit": 20
  }'
```

### Phản hồi thành công (200)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "message": null,
  "data": {
    "total": 20,
    "has_next": true,
    "next_cursor": "cursor_ghi789",
    "tweets": [
      {
        "id": "...",
        "content": "...",
        "author": { "user_id": "...", "username": "..." },
        "created_at": "2026-03-09T12:00:00Z",
        "metrics": { "retweet_count": 100, "favorite_count": 500 }
      }
    ]
  }
}
```

### Trường phản hồi

| Trường | Kiểu | Mô tả |
|-------|------|-------------|
| `total` | integer | Tổng số kết quả |
| `has_next` | boolean | Có thêm kết quả hay không |
| `next_cursor` | string | Con trỏ cho trang tiếp theo |
| `tweets` | array | Danh sách đối tượng tweet (xem mục 3) |

---

## 5. Lấy phản hồi tweet

Truy xuất phản hồi cho các tweet cụ thể.

### Endpoint

```
POST https://openapi.felo.ai/v2/x/tweet/replies
```

### Phần thân yêu cầu

| Tham số | Kiểu | Bắt buộc | Mô tả |
|-----------|------|----------|-------------|
| `tweet_ids` | mảng chuỗi | Có | ID tweet cần lấy phản hồi |
| `cursor` | string | Không | Con trỏ phân trang |
| `since_time` | integer | Không | Bộ lọc thời gian bắt đầu (dấu thời gian Unix) |
| `until_time` | integer | Không | Bộ lọc thời gian kết thúc (dấu thời gian Unix) |

### Ví dụ

```bash
curl -X POST 'https://openapi.felo.ai/v2/x/tweet/replies' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "tweet_ids": ["1234567890"]
  }'
```

### Phản hồi thành công (200)

```json
{
  "status": 200,
  "code": "OK",
  "request_id": "req_example",
  "message": null,
  "data": {
    "results": [
      {
        "tweet_id": "1234567890",
        "total": 10,
        "has_next": true,
        "next_cursor": "cursor_jkl012",
        "replies": [
          {
            "id": "...",
            "content": "Great tweet!",
            "author": { "user_id": "...", "username": "..." },
            "created_at": "2026-03-09T12:30:00Z"
          }
        ]
      }
    ]
  }
}
```

### Trường phản hồi

| Trường | Kiểu | Mô tả |
|-------|------|-------------|
| `results` | array | Danh sách đối tượng kết quả phản hồi |
| `results[].tweet_id` | string | ID tweet gốc |
| `results[].total` | integer | Tổng số phản hồi |
| `results[].has_next` | boolean | Có thêm phản hồi hay không |
| `results[].next_cursor` | string | Con trỏ cho trang tiếp theo |
| `results[].replies` | array | Danh sách đối tượng tweet phản hồi (xem mục 3) |

---

## Mã lỗi

| Mã | Trạng thái HTTP | Mô tả |
|------|-------------|-------------|
| `INVALID_API_KEY` | 401 | API Key không hợp lệ hoặc đã bị thu hồi |
| `X_SEARCH_INVALID_PARAMETER` | 400 | Tham số yêu cầu không hợp lệ |
| `X_SEARCH_PRO_REQUIRED` | 403 | Cần thuê bao PRO để dùng X API |
| `X_SEARCH_FORBIDDEN` | 403 | Bạn không được phép truy cập tài nguyên này |
| `X_SEARCH_NOT_FOUND` | 404 | Không tìm thấy tài nguyên được yêu cầu |
| `INSUFFICIENT_CREDITS` | 402 | Không đủ tín dụng để hoàn tất yêu cầu |
| `RATE_LIMITED` | 429 | Quá nhiều yêu cầu, vui lòng thử lại sau một khoảng ngắn |
| `X_SEARCH_FAILED` | 400/502/503 | Yêu cầu tìm kiếm X thất bại (lỗi client chưa phân loại, lỗi downstream, hoặc không thể xác minh trạng thái thuê bao) |

Trường `message` mang nguyên văn thông báo lỗi downstream khi có sẵn, vì vậy 402 sẽ là `Insufficient credits available` thay vì một lỗi chung chung.

---

## Yêu cầu thuê bao

Tất cả endpoint X đều yêu cầu một **thuê bao PRO** đang hoạt động. Các yêu cầu từ tài khoản miễn phí sẽ bị từ chối với HTTP 403 và mã `X_SEARCH_PRO_REQUIRED`, bất kể số dư tín dụng — nạp thêm tín dụng không cấp quyền truy cập, nâng cấp thuê bao mới cấp.

Nếu dịch vụ thuê bao không thể truy cập, yêu cầu sẽ thất bại với HTTP 503 thay vì bị coi như tài khoản miễn phí, vì vậy một sự cố tạm thời sẽ không âm thầm hạ cấp một khách hàng trả phí. Hãy thử lại sau một khoảng ngắn.

---

## Tín dụng & Giới hạn tốc độ

### Chi phí tín dụng

Mỗi cuộc gọi API sẽ trừ tín dụng dựa trên số lượng kết quả trả về:

| Endpoint | Chi phí tín dụng |
|----------|-------------|
| `POST /x/user/info` | 1 tín dụng cho mỗi người dùng được trả về |
| `POST /x/user/search` | 1 tín dụng cho mỗi người dùng được trả về |
| `POST /x/user/tweets` | 1 tín dụng cho mỗi tweet được trả về |
| `POST /x/tweet/search` | 1 tín dụng cho mỗi tweet được trả về |
| `POST /x/tweet/replies` | 1 tín dụng cho mỗi phản hồi được trả về |

Tín dụng bị trừ sau khi yêu cầu hoàn tất, dựa trên số lượng kết quả thực tế. Nếu một yêu cầu trả về 0 kết quả, sẽ không trừ tín dụng nào.

**Yêu cầu số dư tối thiểu:** Tài khoản của bạn phải có ít nhất 10 tín dụng để thực hiện bất kỳ yêu cầu X API nào. Các yêu cầu được thực hiện với ít hơn 10 tín dụng sẽ bị từ chối với HTTP 402.

### Giới hạn tốc độ

Không có giới hạn tốc độ khi số dư thấp trên các endpoint này: nó chỉ từng áp dụng cho tài khoản miễn phí, và tài khoản miễn phí giờ không còn truy cập được X API nữa (xem [Yêu cầu thuê bao](#y-u-c-u-thu-bao)). Người dùng PRO không bị giới hạn tốc độ bất kể số dư tín dụng.

Khi bị giới hạn tốc độ, API trả về HTTP 429. Header `Retry-After` cho biết thời gian chờ khuyến nghị tính bằng giây.
