X 데이터

필요한 데이터에 맞는 작업을 선택하세요. 이 다섯 개의 엔드포인트는 모두 POST를 사용하며, 공통 data 래퍼 없이 JSON을 루트에서 반환합니다.

모든 예시는 개요의 FELO_API_KEY를 사용합니다. 호출은 Felo Pro 크레딧이 아니라 플랫폼 잔액을 사용합니다. 응답 예시는 설명용이며, 실제 콘텐츠와 선택적 필드는 달라질 수 있습니다.

작업 선택하기

1. 사용자 프로필 가져오기

POST /api/v1/data/x/user/info

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/info" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["OpenAI"]}'

응답에는 users와 total이 포함됩니다. 각 사용자는 user_id, username, display_name을 포함하며, 프로필 텍스트, 팔로워 수, 인증 여부 및 기타 메타데이터도 있을 수 있습니다. 한 배치에서 요청한 수보다 적은 프로필이 반환될 수 있습니다. 배열 위치가 아니라 사용자명 또는 ID로 일치시키세요.

{"users":[{"user_id":"example-user-id","username":"example","display_name":"Example"}],"total":1}

2. 사용자 검색

POST /api/v1/data/x/user/search

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"AI research"}'

응답에는 users, total, has_next, next_cursor가 포함됩니다. 이 작업에는 limit 매개변수가 없습니다.

{"users":[],"total":0,"has_next":false,"next_cursor":null}

3. 사용자 타임라인 가져오기

POST /api/v1/data/x/user/tweets

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/tweets" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"OpenAI","limit":20,"include_replies":false}'

응답에는 tweets, total, has_next, next_cursor가 포함됩니다. limit을 20 미만으로 설정해도 반환 항목 수가 줄거나 요금이 줄어든다는 보장은 없습니다. 답글을 포함하면 반환 데이터와 과금 대상 결과가 늘어날 수 있습니다.

결과 및 중첩 답글 제한

limit은 이 요청의 상위 게시물 목표 수이며, 보장된 결과 수가 아닙니다. 현재 구현은 최소 20의 목표를 사용합니다. 목표가 20이면 상위 1개 페이지를 읽고, 더 큰 목표는 최대 50페이지까지 자동으로 가져옵니다. 각 페이지를 읽기 전에 경과 시간을 확인하며, 60초를 초과하면 더 이상 페이지를 가져오지 않습니다. 이 검사는 전체 HTTP 요청이 60초 안에 끝난다는 보장은 아닙니다.

수집은 목표에 도달했거나, 상위 계층에 다음 페이지가 없거나, 페이지가 비어 있거나, 커서가 없을 때도 중단됩니다. 따라서 성공 응답에 limit보다 적은 게시물이 포함될 수 있습니다. 계속 진행할 수 있는 경우 has_next와 next_cursor를 사용하세요.

include_replies=true이면, 반환된 각 게시물마다 최대 5개의 추가 페이지와 최대 100개의 중첩 답글이 포함됩니다. 다음 페이지가 없거나, 페이지가 비어 있거나, 커서가 더 이상 진행할 수 없을 때 더 일찍 중단될 수 있습니다. 이러한 중첩 답글은 상위 수준의 limit과 total 범위 밖이지만, 과금 대상 결과를 늘릴 수 있습니다.

중첩 replies는 완전한 답글 아카이브가 아니며, 이 추가 수집용 별도 continuation cursor를 제공하지 않습니다. 답글을 독립적으로 페이지네이션하려면 Read replies 작업과 해당 반환 커서를 사용하세요. 답글에는 상위 게시물 커서를 재사용하지 마세요.

4. 게시물 검색

POST /api/v1/data/x/tweet/search

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/tweet/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"retrieval augmented generation","query_type":"Latest","limit":20}'

응답에는 tweets, total, has_next, next_cursor가 포함됩니다. 게시물 객체에는 id, content, author, created_at, metrics가 포함되며, 답글과 인용/리트윗된 게시물이 중첩될 수 있습니다. ID는 문자열로 취급하세요.

결과 수 제한

limit은 보장값이 아니라 목표값입니다. 현재 구현은 최소 20의 목표를 사용합니다. 목표가 20이면 상위 1개 페이지를 읽고, 더 큰 목표는 최대 50페이지까지 자동으로 가져옵니다. 각 페이지를 읽기 전에 경과 시간을 확인하며, 60초를 초과하면 더 이상 페이지를 가져오지 않습니다. 진행 중인 상위 요청은 여전히 시간이 걸릴 수 있으므로, 이는 전체 HTTP 타임아웃이 아닙니다.

수집은 목표에 도달했거나, 상위 계층에 다음 페이지가 없거나, 페이지가 비어 있거나, 커서가 없을 때도 중단됩니다. limit보다 적은 게시물을 반환했다고 해서 요청이 실패한 것은 아니며, 모든 일치 게시물을 가져왔다는 뜻도 아닙니다. 계속하기 전에 has_next와 next_cursor를 확인하세요.

{
  "tweets": [{
    "id":"example-post-id",
    "content":"Example post content",
    "author":{"user_id":"example-user-id","username":"example","display_name":"Example"},
    "created_at":"2026-11-01T00:00:00Z",
    "metrics":{},
    "replies":[]
  }],
  "total":1,
  "has_next":false,
  "next_cursor":null
}

5. 답글 읽기

POST /api/v1/data/x/tweet/replies

플레이스홀더를 실제 게시물 ID로 바꾸세요:

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/tweet/replies" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tweet_ids":["POST_ID"]}'

타임라인 및 게시물 검색과 달리, 답글은 results 아래에 그룹화됩니다. 각 항목은 자체 페이지네이션 상태를 가집니다:

{"results":[{"tweet_id":"POST_ID","replies":[],"total":0,"has_next":false,"next_cursor":null}]}

요청당 답글 제한

각 요청은 tweet_id당 상위 답글 페이지 1개를 읽고 최대 100개의 답글만 보존합니다. 모든 답글 페이지를 자동으로 가져오지는 않습니다. 최대 20개 ID 배치에서 100개 답글 제한은 각 results 항목에 별도로 적용됩니다. 실제 개수는 더 적을 수 있습니다.

각 항목의 total은 해당 항목에서 반환된 답글 수이며, 게시물의 전체 답글 수가 아닙니다. 계속하려면 해당 항목의 next_cursor를 사용하고, 다음 요청에는 그 단일 게시물 ID만 보내세요. 요청당 상한을 늘리는 limit 매개변수는 없습니다.

페이지네이션 및 비용 제어

total은 현재 응답의 해당 배열 수를 의미합니다. 게시물 쿼리에서는 최상위 게시물 수이고, 답글 쿼리에서는 각 결과 항목 내의 답글 수입니다. 전역 일치 수도 아니고, 게시물의 전체 답글 수도 아니며, 최종 과금 대상 수도 아닙니다.

1. cursor 없이 첫 요청을 보내세요.
2. 응답에서 has_next와 next_cursor를 읽으세요. 답글의 경우 각 결과 항목에서 읽으세요.
3. 다음 페이지가 있고 커서가 비어 있지 않으면, 같은 쿼리로 변경하지 않고 그대로 보내세요. 답글 배치의 경우 각 게시물을 별도로 계속하세요.
4. 다음 페이지가 없거나, 커서가 반복되거나, 자체 페이지 또는 지출 한도에 도달하면 중단하세요.

페이지네이션 메타데이터는 마지막 상위 응답을 반영하며, 반환된 컬렉션은 결과 상한에서 잘릴 수 있습니다. has_next=false라도 모든 X 기록이나 답글을 모두 가져왔다는 보장은 아닙니다. 제한된 결과 집합을 가능한 모든 데이터로 표시하지 말고, 실제 반환 수를 표시하세요.

성공한 각 페이지에는 요금이 발생할 수 있습니다. 이 다섯 작업은 고정 요청 요금이 아니라 반환 결과 기준으로 과금됩니다. 중첩 답글 및 기타 반환 레코드는 과금 대상 수에 영향을 줄 수 있으므로, 최상위 배열 길이만으로 비용을 추정하지 마세요. 현재 가격과 콘솔의 사용량을 확인하세요. 완전한 객체 필드는 OpenAPI 스키마에 있습니다.