메인 콘텐츠로 건너뛰기
이 페이지는 최신 검색 또는 전체 보관함 검색 엔드포인트를 시스템에 통합할 때 알아두어야 할 여러 도구와 핵심 개념을 설명합니다. 이 페이지는 다음 섹션으로 구성되어 있습니다:
핵심 개념을 살펴보기 전에, 이러한 엔드포인트의 기능을 테스트해 보기 위해 아래의 도구나 코드 샘플 중 하나를 사용하시길 권장합니다.
선호하는 프로그래밍 언어로 이 엔드포인트를 빠르게 설정하고 싶으신가요? GitHub 페이지에서 시작점으로 활용할 수 있는 다양한 코드 샘플을 제공하며, 여기에는 Python 클라이언트와 Ruby 클라이언트도 포함되어 있습니다.
시작에 도움이 되는 커뮤니티 서드파티 라이브러리 중 하나를 활용하세요. 해당 버전 태그를 확인하여 v2 엔드포인트와 호환되는 라이브러리를 찾을 수 있습니다.
Postman은 이러한 엔드포인트를 테스트하는 데 유용한 도구입니다. 각 Postman 요청에는 해당 엔드포인트의 모든 매개변수가 포함되어 있어, 어떤 옵션을 사용할 수 있는지 빠르게 파악하는 데 도움이 됩니다. Postman 컬렉션에 대해 자세히 알아보려면 Postman 사용 방법 페이지를 방문하세요.
모든 X API v2 엔드포인트는 요청을 인증하기 위한 자격 증명(‘키와 토큰’) 세트를 필요로 합니다. 최근 검색 엔드포인트의 요청 인증에는 OAuth 1.0a 사용자 컨텍스트, OAuth 2.0 App-Only, 또는 OAuth 2.0 Authorization Code with PKCE 중 하나를 사용할 수 있습니다. 전체 아카이브 검색 엔드포인트를 사용할 때는 반드시 OAuth 2.0 App-Only를 사용해야 합니다.
OAuth 2.0 App-Only는 요청에 OAuth 2.0 App 액세스 토큰만 함께 전달하면 됩니다. Developer 앱에서 직접 App 액세스 토큰을 생성하거나, POST oauth2/token 엔드포인트를 사용해 생성할 수 있습니다.
OAuth 1.0a 사용자 컨텍스트는 API 키, 사용자 액세스 토큰, 그리고 몇 가지 추가 매개변수를 사용해 Authorization 헤더를 생성한 뒤 이를 요청에 포함해야 합니다. 액세스 토큰은 요청을 대행하는 대상 사용자와 연결되어 있어야 합니다. 다른 사용자를 위한 액세스 토큰 세트를 생성하려면, 해당 사용자가 3-legged OAuth 플로우를 통해 귀하의 앱을 승인해야 합니다.
OAuth 1.0a는 사용하기 어려울 수 있습니다. 이 인증 방식에 익숙하지 않다면 라이브러리를 사용하거나 Postman 같은 도구를 사용하거나, OAuth 2.0으로 요청을 인증할 것을 권장합니다. 이러한 엔드포인트에서 게시물 또는 비공개 메트릭을 요청하려면, 해당 콘텐츠 소유자의 적절한 권한을 보장하는 OAuth 1.0a 사용자 컨텍스트 또는 OAuth 2.0 Authorization Code with PKCE를 사용해야 합니다.
OAuth 2.0 Authorization Code with PKCE는 애플리케이션의 스코프에 대한 보다 정교한 제어와 여러 기기에 걸친 인증 플로우를 지원합니다. OAuth 2.0을 사용하면 사용자 대리로 세분화된 스코프를 선택해 구체적인 권한을 부여할 수 있습니다.
앱에서 OAuth 2.0을 사용하려면, 개발자 포털의 앱 설정 섹션에 있는 앱 인증 설정에서 이를 활성화해야 합니다.
유의 사항다음 필드를 요청하는 경우, OAuth 1.0a 사용자 컨텍스트 또는 OAuth 2.0 Authorization Code가 필요합니다:
- tweet.fields.non_public_metrics
- tweet.fields.promoted_metrics
- tweet.fields.organic_metrics
- media.fields.non_public_metrics
- media.fields.promoted_metrics
- media.fields.organic_metrics
- tweet.fields.non_public_metrics
- tweet.fields.promoted_metrics
- tweet.fields.organic_metrics
- media.fields.non_public_metrics
- media.fields.promoted_metrics
- media.fields.organic_metrics
위 필드에는 비공개 지표가 포함되므로, 최근 검색 엔드포인트를 사용할 때 게시물 게시자를 대신해 이 데이터를 가져오려면 해당 게시자의 승인이 필요하며, 이를 위해 OAuth 1.0a 사용자 컨텍스트를 사용해야 합니다. 이 인증 방식은 최근 검색에서만 사용할 수 있으므로 전체 아카이브 검색 엔드포인트로는 이러한 지표를 조회할 수 없습니다.
예를 들어 사용자 ID 1234의 게시물에 대한 non_public_metrics를 받으려면 해당 사용자와 연결된 액세스 토큰을 요청에 포함해야 합니다. 3-legged OAuth 플로우를 사용하면 사용자가 앱을 승인하고, 그 사용자와 연결된 액세스 토큰 세트를 발급받을 수 있습니다.
모든 non_public_metrics, organic_metrics, 및 promoted_metrics는 최근 30일 이내에 생성된 게시물에만 제공됩니다. 즉, 위 필드를 요청하면 결과는 자동으로 최근 30일의 게시물만 포함하도록 제한됩니다.
이러한 필드를 요청한 경우 인증된 사용자가 작성한 게시물만 반환되며, 그 외 게시물에는 오류가 반환됩니다.
이 엔드포인트의 핵심 기능은 단일 검색 쿼리를 사용해 전달받을 게시물을 필터링하는 것입니다. 이러한 쿼리는 메시지 키워드, 해시태그, URL 등 게시물 및 사용자 속성과 일치시키는 연산자로 구성됩니다. 연산자는 불리언 논리와 괄호를 사용해 결합할 수 있으며, 이를 통해 쿼리의 매칭 동작을 더욱 정교하게 다듬을 수 있습니다.
쿼리 작성 방법 가이드를 참고해 자세히 알아보세요.
이 엔드포인트는 응답을 빠르게 제공하기 위해 페이지네이션을 사용합니다. 단일 응답으로 전달할 수 있는 범위를 초과하는 결과가 있는 경우(최근 검색은 게시물 최대 100개, 전체 아카이브 검색은 최대 500개) 페이지네이션이 필요합니다. 페이지당 반환할 결과 수를 지정하려면 max_results 매개변수를, 다음 페이지의 결과를 가져오려면 pagination_token 매개변수를 사용하세요. 자세한 내용은 페이지네이션 가이드를 참고하세요.
검색 게시물 엔드포인트는 페이지네이션과 관계없이 월별로 반환할 수 있는 게시물 수에 제한이 있습니다.
어떤 검색 엔드포인트를 사용하더라도 반환된 게시물은 프로젝트 수준의 게시물 상한에 산정됩니다. 사용량은 개발자 포털에 표시되며, ‘월’은 개발자 포털 대시보드에 표시된 구독 갱신일부터 시작됩니다.
게시물 편집
편집 가능한 게시물은 원본 게시가 이루어진 후 30분 동안 최대 5회까지 편집할 수 있습니다. 검색 엔드포인트는 항상 해당 게시물의 최신 버전을 제공합니다. 게시된 지 30분 이상 지난 게시물만 요청하는 경우, 항상 최종 버전을 받게 됩니다. 그러나 준실시간 사용 사례로 지난 30분 이내에 게시된 게시물을 조회하는 경우에는, 수신 후에 편집되었을 수 있습니다. 이러한 게시물은 검색 또는 게시물 조회 엔드포인트로 다시 조회하여 최종 상태를 확인할 수 있습니다. 게시물 편집 동작에 대한 자세한 내용은 게시물 편집 기본 사항 페이지를 참조하세요.
다음 단계
검색 게시물 엔드포인트에 첫 요청 보내기
API Reference 페이지에서 전체 매개변수, 필드 등 확인하기
지원 받기 또는 오류 문제 해결 
