Felo API PlatformFelo API Platform

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/search

Xá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_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ểuBắt buộcMô tả
usernamesmảng chuỗiCó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ườngKiểuMô tả
user_idstringID người dùng X
usernamestringHandle X (không có @)
display_namestringTên hiển thị
descriptionstringTiểu sử người dùng
followers_countintegerSố người theo dõi
following_countintegerSố tài khoản đang theo dõi
tweet_countintegerTổng số tweet
verifiedbooleanTài khoản có được xác minh hay không
blue_verifiedbooleanTài khoản có xác minh Blue hay không
verified_typestringLoại xác minh
profile_image_urlstringURL ảnh đại diện
cover_image_urlstringURL ảnh bìa
created_atstringThời điểm tạo tài khoản
locationstringVị trí người dùng
urlstringURL trang web của người dùng
protectedbooleanTài khoản có được bảo vệ hay không
favorites_countintegerSố lượt thích
media_countintegerSố bài đăng có media
can_dmbooleanDM có mở hay không
is_automatedbooleanTài khoản có tự động hóa hay không
pinned_tweet_idsmảng chuỗiID 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ểuBắt buộcMô tả
querystringCóTừ khóa tìm kiếm
cursorstringKhôngCon 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ườngKiểuMô tả
totalintegerTổng số kết quả
has_nextbooleanCó thêm kết quả hay không
next_cursorstringCon trỏ cho trang tiếp theo
usersarrayDanh 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ểuBắt buộcMô tả
x_user_idstringKhôngID người dùng X (cung cấp либо x_user_id hoặc username)
usernamestringKhôngUsername X (cung cấp либо x_user_id hoặc username)
limitintegerKhôngSố tweet cần trả về
cursorstringKhôngCon trỏ phân trang
include_repliesbooleanKhôngCó 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ườngKiểuMô tả
idstringID tweet
contentstringNội dung văn bản tweet
authorobjectĐối tượng người dùng tác giả (xem mục 1)
created_atstringThời điểm tạo tweet
metricsobjectChỉ số tương tác (xem bên dưới)
repliesarrayCác tweet phản hồi (nếu có)
conversation_idstringID luồng hội thoại
media_urlsarrayMedia đính kèm
hashtagsarray of stringsHashtag trong tweet
mentionsarray of stringsCác username được nhắc tới
urlsarray of stringsURL trong tweet
urlstringPermalink tới tweet
sourcestringNguồn tweet (ví dụ "Twitter Web App")
langstringMã ngôn ngữ của tweet
is_replybooleanĐây có phải phản hồi hay không
in_reply_to_idstringID của tweet được phản hồi
in_reply_to_user_idstringID người dùng của tweet được phản hồi
in_reply_to_usernamestringUsername của tweet được phản hồi
quoted_tweetobjectĐối tượng tweet được trích dẫn (đệ quy)
retweeted_tweetobjectĐối tượng tweet được đăng lại (đệ quy)
is_limited_replybooleanPhản hồi có bị giới hạn hay không

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

TrườngKiểuMô tả
retweet_countintegerSố lần đăng lại
favorite_countintegerSố lượt thích
reply_countintegerSố phản hồi
quote_countintegerSố lần trích dẫn
view_countintegerSố lượt xem
bookmark_countintegerSố 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ểuBắt buộcMô tả
querystringCóTruy vấn tìm kiếm (hỗ trợ cú pháp tìm kiếm nâng cao)
query_typestringKhôngBộ lọc loại truy vấn
since_timeintegerKhôngBộ lọc thời gian bắt đầu (dấu thời gian Unix tính bằng giây)
until_timeintegerKhôngBộ lọc thời gian kết thúc (dấu thời gian Unix tính bằng giây)
limitintegerKhôngSố tweet cần trả về
cursorstringKhôngCon 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ườngKiểuMô tả
totalintegerTổng số kết quả
has_nextbooleanCó thêm kết quả hay không
next_cursorstringCon trỏ cho trang tiếp theo
tweetsarrayDanh 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ểuBắt buộcMô tả
tweet_idsmảng chuỗiCóID tweet cần lấy phản hồi
cursorstringKhôngCon trỏ phân trang
since_timeintegerKhôngBộ lọc thời gian bắt đầu (dấu thời gian Unix)
until_timeintegerKhôngBộ 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ườngKiểuMô tả
resultsarrayDanh sách đối tượng kết quả phản hồi
results[].tweet_idstringID tweet gốc
results[].totalintegerTổng số phản hồi
results[].has_nextbooleanCó thêm phản hồi hay không
results[].next_cursorstringCon trỏ cho trang tiếp theo
results[].repliesarrayDanh sách đối tượng tweet phản hồi (xem mục 3)

Mã lỗi

MãTrạng thái HTTPMô tả
INVALID_API_KEY401API Key không hợp lệ hoặc đã bị thu hồi
X_SEARCH_INVALID_PARAMETER400Tham số yêu cầu không hợp lệ
X_SEARCH_PRO_REQUIRED403Cần thuê bao PRO để dùng X API
X_SEARCH_FORBIDDEN403Bạn không được phép truy cập tài nguyên này
X_SEARCH_NOT_FOUND404Không tìm thấy tài nguyên được yêu cầu
INSUFFICIENT_CREDITS402Không đủ tín dụng để hoàn tất yêu cầu
RATE_LIMITED429Quá nhiều yêu cầu, vui lòng thử lại sau một khoảng ngắn
X_SEARCH_FAILED400/502/503Yê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ề:

EndpointChi phí tín dụng
POST /x/user/info1 tín dụng cho mỗi người dùng được trả về
POST /x/user/search1 tín dụng cho mỗi người dùng được trả về
POST /x/user/tweets1 tín dụng cho mỗi tweet được trả về
POST /x/tweet/search1 tín dụng cho mỗi tweet được trả về
POST /x/tweet/replies1 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?