메인 콘텐츠로 건너뛰기
이 페이지에는 시스템에 사용자 조회 엔드포인트를 통합할 때 알아두어야 할 여러 도구와 핵심 개념에 대한 정보가 포함되어 있습니다. 이 페이지는 다음과 같은 섹션으로 구성되어 있습니다:

​
유용한 도구

이 엔드포인트를 통합하는 데 도움이 될 몇 가지 핵심 개념을 살펴보기 전에, 먼저 다음 항목에 익숙해지시길 권장합니다:

​
Postman

Postman은 엔드포인트를 테스트하는 데 유용한 도구입니다. 각 Postman 요청에는 사용 가능한 항목을 빠르게 파악할 수 있도록 모든 경로 및 본문 매개변수가 포함되어 있습니다. Postman 컬렉션에 대해 더 알아보려면 “Postman 사용하기” 페이지를 방문하세요. 

​
코드 샘플

선호하는 프로그래밍 언어로 이 엔드포인트를 설정하는 코드가 필요하신가요? 시작점으로 활용할 수 있는 다양한 코드 샘플을 GitHub 페이지에서 확인하실 수 있습니다.

​
서드파티 라이브러리

X 커뮤니티에서 제공하는 서드파티 라이브러리를 활용해 시작해 보세요. v2 엔드포인트와 호환되는 라이브러리는 해당 버전 태그를 확인해 찾을 수 있습니다.

​
핵심 개념

​
인증

모든 X API v2 엔드포인트는 키와 토큰으로 알려진 자격 증명 세트로 요청을 인증해야 합니다. 이러한 엔드포인트에 대한 요청 인증에는 OAuth 1.0a 사용자 컨텍스트, 앱 전용, 또는 OAuth 2.0 Authorization Code with PKCE 중 하나를 사용할 수 있습니다. OAuth 1.0a 사용자 컨텍스트는 요청에 함께 전달할 authorization 헤더를 생성하기 위해 API 키, 사용자 액세스 토큰, 그리고 일부 추가 매개변수를 사용해야 합니다. 액세스 토큰은 요청을 대행하려는 해당 사용자와 연관되어 있어야 합니다. 다른 사용자의 액세스 토큰 세트를 생성하려면, 해당 사용자가 3-legged OAuth 플로우를 통해 여러분의 App을 승인해야 합니다. OAuth 1.0a는 사용이 까다로울 수 있습니다. 이 인증 방식에 익숙하지 않다면 라이브러리를 사용하거나 Postman과 같은 도구를 이용하거나, OAuth 2.0으로 요청을 인증하시길 권장합니다. 이러한 엔드포인트에서 게시물이나 비공개 메트릭을 요청하려면 OAuth 1.0a 사용자 컨텍스트 또는 OAuth 2.0 Authorization Code with PKCE를 사용해야 하며, 이를 통해 해당 콘텐츠 소유 사용자로부터 적절한 권한을 보유했음을 보장합니다. 앱 전용은 요청에 앱 전용 액세스 토큰만 포함하면 됩니다. 앱 전용 액세스 토큰은 Developer 앱 내에서 직접 생성하거나 POST oauth2/token 엔드포인트로 생성할 수 있습니다. OAuth 2.0 Authorization Code with PKCE는 애플리케이션의 스코프를 더 세밀하게 제어하고 여러 기기에 걸친 권한 부여 플로우를 지원합니다. OAuth 2.0을 사용하면 사용자 대신 수행할 수 있는 권한을 세밀한 스코프로 선택할 수 있습니다. App에서 OAuth 2.0을 사용하려면, 개발자 포털의 App 설정 섹션에 있는 인증 설정에서 이를 활성화해야 합니다. 참고 다음 필드를 요청하는 경우 OAuth 1.0a 사용자 컨텍스트 또는 OAuth 2.0 Authorization Code가 필요합니다:
  • tweet.fields.non_public_metrics
  • tweet.fields.promoted_metrics
  • tweet.fields.organic_metrics

​
개발자 포털, 프로젝트, 그리고 Developer 앱

X API v2 엔드포인트와 함께 사용할 인증 자격 증명 세트를 얻으려면 개발자 계정에 가입하고, 해당 계정 내에 프로젝트를 설정한 뒤, 그 프로젝트 내에 Developer 앱을 생성해야 합니다. 그런 다음 Developer 앱에서 키와 토큰을 확인할 수 있습니다.   

​
요청 한도

매일 수천 명의 개발자가 X API에 요청을 보냅니다. 이러한 대규모 요청을 효율적으로 관리하기 위해 각 엔드포인트에는 요청 한도가 설정되어 있으며, 이는 앱 또는 인증된 사용자를 대신해 보낼 수 있는 요청 수를 제한합니다. 사용자 조회 엔드포인트에는 앱 수준과 사용자 수준의 요청 한도가 모두 적용됩니다. 다만, 인증된 사용자 조회 엔드포인트는 사용자 수준 요청 한도만 적용됩니다. 앱 수준 요청 한도는 개발자인 여러분이 특정 기간 동안 사용하는 App(여러분이 사용하는 키와 토큰으로 식별됨)에서 해당 엔드포인트로 보낼 수 있는 요청 수가 제한됨을 의미합니다. 사용자 수준 요청 한도는 여러분이 대신하여 요청을 수행하는 인증된 사용자가 모든 Developer 앱을 통틀어 수행할 수 있는 횟수가 제한됨을 의미합니다. 아래 표는 각 엔드포인트의 요청 한도를 보여줍니다.
엔드포인트HTTP 메서드요청 한도 / 레벨
/2/usersGET15분당 900회 요청 / App 및 User
/2/users/:idGET15분당 900회 요청 / App 및 User
/2/users/byGET15분당 900회 요청 / App 및 User
/2/users/by/username/:usernameGET15분당 900회 요청 / App 및 User
/2/users/meGET15분당 75회 요청 / User

​
필드와 expansions

X API v2는 필드와 expansions라는 도구 세트를 사용해 API에서 반환받을 데이터를 정확히 지정할 수 있도록 합니다. expansions 매개변수는 페이로드에서 참조된 객체를 결과에 확장해 포함시킵니다. 예를 들어, 이 엔드포인트에서는 pinned_tweet_id expansion을 사용할 수 있습니다. fields 매개변수는 서로 다른 데이터 객체에서 수신하려는 필드를 정확히 선택할 수 있게 합니다. 이 엔드포인트들은 주로 사용자 객체를 반환합니다. 기본적으로 사용자 객체는 id, name, username 필드를 반환합니다. user.created_at 또는 user.location과 같은 추가 필드를 받으려면 fields 매개변수로 명시적으로 요청해야 합니다. 통합 시 고려할 만한 중요한 필드로는 게시물 설문 데이터, 메트릭, 주석, 그리고 대화 ID 필드가 있습니다. X API v2 데이터 사전에 fields와 expansions 사용 방법 가이드를 추가했습니다.

​
예외 상황

  • 리트윗에서는 게시물 텍스트가 잘릴 수 있습니다. 단기적인 해결책으로는 참조된 게시물을 확장하고, 그 확장에서 전체 텍스트를 가져오면 됩니다. 이는 버그이며 향후 수정할 예정입니다.