메인 콘텐츠로 건너뛰기
이 가이드는 애플리케이션에 Search Posts 엔드포인트를 통합하는 데 필요한 핵심 개념을 다룹니다.

​
인증

최근 검색은 여러 인증 방식을 지원합니다:
방식사용 사례
OAuth 2.0 App-Only공개 게시물 데이터
OAuth 2.0 Authorization Code with PKCE비공개 메트릭
OAuth 1.0a User Context비공개 메트릭
전체 아카이브 검색은 OAuth 2.0 App-Only 인증만 지원합니다.
전체 아카이브 검색은 App-Only 인증만 지원하므로, 비공개 지표(non_public_metrics, organic_metrics, promoted_metrics)는 사용할 수 없습니다.

​
쿼리 작성하기

쿼리는 연산자를 사용해 포스트를 일치시킵니다. 불리언 논리로 연산자를 조합하세요: 
(AI OR "machine learning") lang:en -is:retweet has:links

​
쿼리 길이 제한

액세스 레벨최근 검색전체 아카이브 검색
셀프 서비스512자1,024자
엔터프라이즈4,096자4,096자

​
연산자 유형

유형설명예시
단독형단독으로 사용할 수 있습니다#python, from:user
조합 필수형단독형 연산자와 함께 사용해야 합니다has:media, is:retweet

쿼리 만들기

쿼리 구문을 자세히 알아보세요

연산자 참조

사용 가능한 모든 연산자를 확인하세요

​
필드와 expansions

기본적으로 응답에는 id, text, edit_history_tweet_ids만 포함됩니다. 추가 데이터를 요청하려면 매개변수를 사용하세요.

​
요청 예시

cURL
curl "https://api.x.com/2/tweets/search/recent?\
query=python&\
tweet.fields=created_at,public_metrics,author_id&\
expansions=author_id,attachments.media_keys&\
user.fields=username,verified&\
media.fields=url,type" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​
사용 가능한 expansions

Expansion반환값
author_id작성자의 사용자 객체
attachments.media_keys첨부된 미디어 객체
attachments.poll_ids첨부된 투표 객체
referenced_tweets.id인용 또는 답글 대상 포스트
geo.place_id장소 객체
entities.mentions.username멘션된 사용자 객체

필드와 expansions 가이드

응답을 맞춤 구성하는 방법을 자세히 알아보세요
검색 엔드포인트는 결과를 페이지로 나누어 반환합니다. 추가 페이지를 조회하려면 응답에 포함된 next_token을 사용하세요.

​
동작 방식

  1. 초기 요청을 보낼 때 max_results를 설정합니다.
  2. meta 객체에서 next_token을 확인합니다.
  3. 이후 요청에 next_token을 포함합니다.
  4. next_token이 더 이상 반환되지 않을 때까지 반복합니다.

​
예시

cURL
# 첫 번째 요청
curl "https://api.x.com/2/tweets/search/recent?query=python&max_results=100" \
  -H "Authorization: Bearer $BEARER_TOKEN"

# 페이지네이션 토큰을 포함한 후속 요청
curl "https://api.x.com/2/tweets/search/recent?query=python&max_results=100&next_token=NEXT_TOKEN" \
  -H "Authorization: Bearer $BEARER_TOKEN"

페이지네이션 가이드

페이지네이션에 대해 자세히 알아보기

​
포스트 수정

포스트는 30분 이내에 최대 5번까지 수정할 수 있습니다. 검색 엔드포인트는 항상 최신 버전을 반환합니다.

​
고려 사항

  • edit_history_tweet_ids에는 모든 게시물 ID가 포함됩니다(가장 오래된 것부터)
  • 30분 제한 시간이 지난 후에 가져온 포스트는 최종 버전으로 간주됩니다
  • 실시간에 가까운 사용 사례에서는 최근에 게시된 포스트가 여전히 수정될 수 있습니다

게시물 수정 기본 사항

게시물 수정에 대해 자세히 알아보기

​
모범 사례

구체적으로 시작하기

여러 연산자를 사용해 결과를 좁히고 노이즈를 줄이세요.

반복적으로 테스트하기

처음에는 범위를 넓게 잡고, 결과를 보면서 점진적으로 정교화하세요.

페이지네이션 처리하기

대용량 결과 집합에는 적절한 페이지네이션을 구현하세요.

결과 캐싱하기

반복 요청을 피하기 위해 결과를 로컬에 저장하세요.

​
다음 단계

쿼리 작성

쿼리 구문 익히기

연산자 참조

사용 가능한 모든 연산자

페이지네이션

대용량 결과 처리

API 참조 문서

엔드포인트 전체 문서