Felo APIs
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.
POST
/v2/x/tweet/searchXác thực
Bearer API key
Loại nội dung
application/json
Ghi chú về giới hạn
1 request per 10 seconds, 3 per minute, 10 per 10 minutes.
X Search API cung cấp quyền truy cập 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à câu trả lời cho tweet.
Xác thực
Mọi yêu cầu đều cần khóa API trong header Authorization:
Authorization: Bearer YOUR_API_KEYDùng với AI Agent
Cài gói felo-ai đầy đủ để cung cấp cho một Agent X Search và mọi Felo Skill khác hiện có. Trình cài đặt tự động khám phá mọi thư mục gói có chứa SKILL.md, thay vì giữ một danh sách Skill cố định. Hãy cài mọi Skill được phát hiện vào 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 để biết hướng dẫn cài đặt, khóa API và xác minh riêng cho từng nền tảng.
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 tên người dùng.
Endpoint
POST https://openapi.felo.ai/v2/x/user/infoNội dung yêu cầu
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
usernames | array of strings | Có | Danh sách tên người dùng X cần tra cứu |
Ví dụ
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)
{
"status": "ok",
"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"
}
]
}
}Các trường của đối tượng người dùng
| Trường | Kiểu | Mô tả |
|---|---|---|
user_id | string | ID người dùng X |
username | string | Tên người dùng 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 hồ sơ |
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 phương tiện |
can_dm | boolean | Tin nhắn trực tiếp có mở hay không |
is_automated | boolean | Tài khoản có tự động hay không |
pinned_tweet_ids | array of strings | Các 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/searchNội dung 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ụ
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)
{
"status": "ok",
"message": null,
"data": {
"total": 50,
"has_next": true,
"next_cursor": "cursor_abc123",
"users": [
{
"user_id": "...",
"username": "...",
"display_name": "..."
}
]
}
}Các 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 các đối tượng người dùng (xem phần 1) |
3. Lấy tweet của người dùng
Truy xuất tweet từ một người dùng X cụ thể.
Endpoint
POST https://openapi.felo.ai/v2/x/user/tweetsNội dung 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 | Tên người dùng 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 câu trả lời hay không |
Ví dụ
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)
{
"status": "ok",
"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"
}
]
}
}Các trường của đối tượng tweet
| Trường | Kiểu | Mô tả |
|---|---|---|
id | string | ID tweet |
content | string | Nội dung văn bản của tweet |
author | object | Đối tượng người dùng tác giả (xem phần 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 trả lời (nếu có) |
conversation_id | string | ID chuỗi hội thoại |
media_urls | array | Phương tiện đính kèm |
hashtags | array of strings | Các hashtag trong tweet |
mentions | array of strings | Các tên người dùng được nhắc đến |
urls | array of strings | Các URL trong tweet |
url | string | Liên kết cố định đến tweet |
source | string | Nguồn của tweet (ví dụ "Twitter Web App") |
lang | string | Mã ngôn ngữ của tweet |
is_reply | boolean | Đây có phải là câu trả lời hay không |
in_reply_to_id | string | ID của tweet đang được trả lời |
in_reply_to_user_id | string | ID người dùng của tweet đang được trả lời |
in_reply_to_username | string | Tên người dùng của tweet đang được trả lờ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 | Câu trả lời có bị giới hạn hay không |
Các trường của đối tượng chỉ số
| 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ố câu trả lờ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 |
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/searchNội dung 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ụ
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)
{
"status": "ok",
"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 }
}
]
}
}Các 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 các đối tượng tweet (xem phần 3) |
5. Lấy câu trả lời cho tweet
Truy xuất câu trả lời cho các tweet cụ thể.
Endpoint
POST https://openapi.felo.ai/v2/x/tweet/repliesNội dung yêu cầu
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
tweet_ids | array of strings | Có | (Các) ID tweet cần lấy câu trả lờ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ụ
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)
{
"status": "ok",
"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"
}
]
}
]
}
}Các trường phản hồi
| Trường | Kiểu | Mô tả |
|---|---|---|
results | array | Danh sách các đối tượng kết quả câu trả lời |
results[].tweet_id | string | ID tweet gốc |
results[].total | integer | Tổng số câu trả lời |
results[].has_next | boolean | Có thêm câu trả lời hay không |
results[].next_cursor | string | Con trỏ cho trang tiếp theo |
results[].replies | array | Danh sách các đối tượng tweet trả lời (xem phần 3) |
Mã lỗi
| Mã | Trạng thái HTTP | Mô tả |
|---|---|---|
UNAUTHORIZED | 401 | Khóa API không hợp lệ hoặc đã bị thu hồi |
X_SEARCH_FAILED | 400/500 | Yêu cầu tìm kiếm X thất bại (kiểm tra tham số hoặc lỗi hạ nguồn) |
RATE_LIMIT_EXCEEDED | 429 | Quá nhiều yêu cầu, vui lòng thử lại sau một khoảng ngắn |
insufficient_credits | 402 | Không đủ tín dụng để hoàn tất yêu cầu |
Tín dụng và giới hạn tần suất
Chi phí tín dụng
Mỗi lệnh gọi API trừ tín dụng dựa trên số kết quả được trả về:
| Endpoint | Chi phí tín dụng |
|---|---|
POST /x/user/info | 1 tín dụng mỗi người dùng được trả về |
POST /x/user/search | 1 tín dụng mỗi người dùng được trả về |
POST /x/user/tweets | 1 tín dụng mỗi tweet được trả về |
POST /x/tweet/search | 1 tín dụng mỗi tweet được trả về |
POST /x/tweet/replies | 1 tín dụng mỗi câu trả lời được trả về |
Tín dụng được trừ sau khi yêu cầu hoàn tất, dựa trên số kết quả thực tế. Nếu một yêu cầu trả về 0 kết quả, không có tín dụng nào bị trừ.
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 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ần suất
Giới hạn tần suất được áp dụng theo dịch vụ API hiện tại và chính sách tài khoản. Khi bị giới hạn tần suất, API trả về HTTP 429. Header Retry-After cho biết thời gian chờ được đề xuất tính bằng giây. Hãy dùng tài liệu dịch vụ mới nhất và phản hồi API thực tế để xử lý giới hạn tần suất; không bắt buộc phải có gói đăng ký để sử dụng nền tảng.