Harness 설정
X Search API
X users, tweets, timelines, replies를 pagination metadata와 함께 검색하세요.
/v2/x/tweet/search인증
Bearer API key
Content type
application/json
속도 제한
1 request per 10 seconds, 3 per minute, 10 per 10 minutes.
X Search API는 X/Twitter 데이터에 접근하는 API입니다. 사용자 프로필, 사용자 검색, 사용자 tweets, tweet 검색, 답글을 가져올 수 있습니다. Agent 리서치, 소셜 리스닝, 계정 분석, 콘텐츠 인사이트에 적합합니다.
인증
Authorization: Bearer YOUR_API_KEY1. 사용자 정보 가져오기
username으로 X 사용자 프로필을 일괄 조회합니다.
POST https://openapi.felo.ai/v2/x/user/info| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
usernames | array of strings | 예 | 조회할 X username 목록 |
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"]}'2. 사용자 검색
키워드로 X 사용자를 검색합니다.
POST https://openapi.felo.ai/v2/x/user/search| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
query | string | 예 | 검색 키워드 |
cursor | string | 아니요 | 이전 응답의 페이지네이션 cursor |
3. 사용자 Tweets 가져오기
특정 X 사용자의 tweets를 가져옵니다.
POST https://openapi.felo.ai/v2/x/user/tweets| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
x_user_id | string | 아니요 | X user ID. x_user_id 또는 username 중 하나를 입력하세요 |
username | string | 아니요 | X username. x_user_id 또는 username 중 하나를 입력하세요 |
limit | integer | 아니요 | 반환할 결과 수 |
cursor | string | 아니요 | 이전 응답의 페이지네이션 cursor |
include_replies | boolean | 아니요 | 답글 포함 여부 |
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}'4. Tweets 검색
키워드로 X tweets를 검색하며 고급 검색 문법을 지원합니다.
POST https://openapi.felo.ai/v2/x/tweet/search| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
query | string | 예 | 검색 쿼리. 고급 검색 문법을 지원합니다 |
query_type | string | 아니요 | 쿼리 타입 필터 |
since_time | integer | 아니요 | 시작 시간 필터, Unix 초 단위 timestamp |
until_time | integer | 아니요 | 종료 시간 필터, Unix 초 단위 timestamp |
limit | integer | 아니요 | 반환할 결과 수 |
cursor | string | 아니요 | 이전 응답의 페이지네이션 cursor |
5. Tweet 답글 가져오기
특정 tweets의 답글을 가져옵니다.
POST https://openapi.felo.ai/v2/x/tweet/replies| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
tweet_ids | array of strings | 예 | 답글을 가져올 Tweet ID |
cursor | string | 아니요 | 이전 응답의 페이지네이션 cursor |
since_time | integer | 아니요 | 시작 시간 필터, Unix 초 단위 timestamp |
until_time | integer | 아니요 | 종료 시간 필터, Unix 초 단위 timestamp |
공통 응답 필드
| 필드 | 타입 | 설명 |
|---|---|---|
total | integer | 반환되었거나 사용 가능한 결과 수 |
has_next | boolean | 추가 결과가 있는지 여부 |
next_cursor | string | 다음 페이지 cursor |
users | array | 사용자 endpoint의 사용자 객체 |
tweets | array | tweet endpoint의 tweet 객체 |
results | array | 답글 endpoint의 결과 객체 |
사용자 객체에는 user_id, username, display_name, description, followers_count, following_count, tweet_count, verified, blue_verified, profile_image_url, created_at, location, url 등이 포함될 수 있습니다.
Tweet 객체에는 id, content, author, created_at, metrics, conversation_id, media_urls, hashtags, mentions, urls, url, lang, 답글 관련 필드, quoted tweet, retweeted tweet 등이 포함될 수 있습니다.
Credits 및 속도 제한
각 API 호출은 반환된 결과 수에 따라 credits를 차감합니다. 요청 결과가 0개라면 credits는 차감되지 않습니다. X API 요청을 보내려면 계정에 최소 10 credits가 필요합니다.
| Endpoint | Credit 비용 |
|---|---|
POST /x/user/info | 반환된 사용자 1명당 1 credit |
POST /x/user/search | 반환된 사용자 1명당 1 credit |
POST /x/user/tweets | 반환된 tweet 1개당 1 credit |
POST /x/tweet/search | 반환된 tweet 1개당 1 credit |
POST /x/tweet/replies | 반환된 답글 1개당 1 credit |
credits 잔액이 100 미만인 비유료 구독 계정에는 속도 제한이 적용됩니다. 제한 시 API는 HTTP 429를 반환하며 Retry-After header에 권장 대기 시간이 초 단위로 표시됩니다.
오류 코드
| Code | HTTP Status | 설명 |
|---|---|---|
INVALID_API_KEY | 401 | API key가 유효하지 않거나 취소되었습니다 |
X_SEARCH_FAILED | 400/500 | X search 요청이 실패했습니다. 파라미터 또는 downstream 오류를 확인하세요 |
RATE_LIMIT_EXCEEDED | 429 | 요청이 너무 많습니다. 잠시 후 다시 시도하세요 |
insufficient_credits | 402 | credits가 부족해 요청을 완료할 수 없습니다 |