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

​
인증

모든 X API v2 엔드포인트에서는 인증이 필요합니다. 사용 사례에 가장 적합한 방법을 선택하세요:
MethodBest forCan access private metrics?
OAuth 2.0 App-Only서버 간 통신, 공개 데이터아니요
OAuth 2.0 Authorization Code with PKCE사용자 대상 애플리케이션예 (승인된 사용자의 데이터)
OAuth 1.0a User Context레거시 통합예 (승인된 사용자의 데이터)

​
App 전용 인증

공개 사용자 데이터를 조회할 때는 Bearer 토큰을 사용합니다:
cURL
curl "https://api.x.com/2/users/by/username/XDevelopers" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​
User Context 인증

인증된 사용자 엔드포인트(/2/users/me)에 필요한 예시는 다음과 같습니다:
cURL
curl "https://api.x.com/2/users/me" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
/2/users/me 엔드포인트는 User Context 인증에서만 사용할 수 있습니다. App-Only 토큰을 사용하면 오류가 반환됩니다.

​
필드 및 expansions

X API v2는 기본적으로 최소한의 데이터만 반환합니다. 필요한 데이터를 정확히 요청하려면 fields와 expansions를 사용하세요.

​
기본 응답

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers"
  }
}

​
사용 가능한 필드

FieldDescription
created_at계정이 생성된 타임스탬프
description사용자 소개
entities소개에 포함된 URL 파싱 결과
location사용자가 지정한 위치
pinned_tweet_id고정된 게시물 ID
profile_image_url프로필 이미지 URL
protected계정이 보호 계정인지 여부
public_metrics팔로워/팔로잉 수
url웹사이트 URL
verified인증 상태
withheld차단/보류 정보
FieldDescription
created_at게시물이 생성된 타임스탬프
text게시물 내용
public_metrics참여 수치
entities해시태그, 멘션, URL

​
필드를 포함한 예제

cURL
curl "https://api.x.com/2/users/by/username/XDevelopers?\
user.fields=created_at,description,public_metrics,verified&\
expansions=pinned_tweet_id&\
tweet.fields=created_at,public_metrics" \
  -H "Authorization: Bearer $BEARER_TOKEN"

​
expansions를 포함한 응답

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "XDevelopers",
    "created_at": "2013-12-14T04:35:55.000Z",
    "verified": true,
    "pinned_tweet_id": "1234567890",
    "public_metrics": {
      "followers_count": 583423,
      "following_count": 2048,
      "tweet_count": 14052
    }
  },
  "includes": {
    "tweets": [
      {
        "id": "1234567890",
        "text": "Welcome to the X Developer Platform!",
        "created_at": "2024-01-15T10:00:00.000Z"
      }
    ]
  }
}

필드 및 Expansions 가이드

응답을 커스터마이징하는 방법을 자세히 알아보세요

​
배치 조회

하나의 요청으로 여러 사용자를 조회할 수 있습니다:
cURL (ID 기준)
curl "https://api.x.com/2/users?ids=2244994945,783214,6253282&\
user.fields=username,verified" \
  -H "Authorization: Bearer $BEARER_TOKEN"
배치 요청은 한 번에 최대 100명의 사용자까지 처리할 수 있습니다. 더 큰 데이터셋에는 여러 개의 요청을 사용하세요.

​
오류 처리

​
일반적인 오류

Status오류해결 방법
400잘못된 요청매개변수 형식을 확인하세요
401인증되지 않음인증 정보를 확인하세요
403접근이 거부됨App 권한을 확인하세요
404찾을 수 없음사용자가 존재하지 않거나 정지되었습니다
429요청이 너무 많음대기 후 다시 시도하세요 (요청 한도 참조)

​
정지되었거나 삭제된 사용자

사용자가 정지되었거나 삭제된 경우:
  • 단일 사용자 조회는 404를 반환합니다
  • 다중 사용자 조회에서는 결과에서 해당 사용자가 제외되며 errors 배열이 포함됩니다
{
  "data": [
    { "id": "2244994945", "username": "XDevelopers" }
  ],
  "errors": [
    {
      "resource_id": "1234567890",
      "resource_type": "user",
      "title": "Not Found Error",
      "detail": "Could not find user with id: [1234567890]."
    }
  ]
}

​
보호된 사용자

팔로우하지 않는 보호된 계정의 경우:
  • 기본 정보(id, name, username)는 확인할 수 있습니다
  • 보호된 콘텐츠(고정된 게시물)에 대한 액세스는 제한될 수 있습니다
  • protected: true는 계정의 상태를 나타냅니다

​
모범 사례

일괄 요청

다중 사용자 엔드포인트를 사용해 한 번에 최대 100명의 사용자를 가져와 API 호출 횟수를 줄이세요.

필요한 필드만 요청

응답 크기를 최소화하기 위해 필요한 필드만 지정하세요.

사용자 데이터 캐싱

반복 요청을 줄이기 위해 사용자 프로필을 로컬에 캐싱하세요.

오류를 우아하게 처리

일괄 응답에서 일부 오류가 있는지 확인하세요.

​
다음 단계

API 참조 문서

엔드포인트 전체 문서

데이터 사전

사용 가능한 모든 객체와 필드

샘플 코드

실행 가능한 코드 예제

오류 처리

오류를 원활하게 처리하기