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.
/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.
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. 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 đượ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 để 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_KEY1. 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/infoPhầ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ụ
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": 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/searchPhầ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ụ
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": 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/tweetsPhầ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ụ
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": 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/searchPhầ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ụ
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": 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/repliesPhầ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ụ
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": 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). 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.
Cần trợ giúp?
- Cần hỏi về API, thanh toán hoặc tài khoản? Liên hệ bộ phận hỗ trợ.
- Trò chuyện với đội ngũ phát triển Felo trên Discord.
- Xem nhật ký thay đổi của chúng tôi.
- Cần báo giá theo số lượng lớn hoặc hỗ trợ mua hàng? Liên hệ kinh doanh.
- Bạn đang xây dựng với LLM? Đọc llms.txt.