첫 요청 보내기

몇 분 만에 X API를 바로 사용해 보세요

이 가이드는 X API에 처음으로 요청을 보내는 과정을 단계별로 안내합니다. 시작하기 전에 App 자격 증명이 있는 개발자 계정이 필요합니다.

---

​

cURL로 빠르게 시작하기

API를 테스트하는 가장 빠른 방법은 cURL을 사용하는 것입니다. 사용자 정보를 한 번 조회해 보겠습니다:

curl "https://api.x.com/2/users/by/username/xdevelopers" \
  -H "Authorization: Bearer $BEARER_TOKEN"

$BEARER_TOKEN을(를) 실제 Bearer 토큰 값으로 교체하세요. 그러면 다음과 같은 응답을 받게 됩니다:

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

---

​

단계별 가이드

1. Bearer 토큰 가져오기

   개발자 콘솔에서 App으로 이동한 다음 Bearer 토큰을 복사합니다.

2. 엔드포인트 선택

   다음과 같은 초보자에게 친숙한 엔드포인트 중 하나로 시작하세요:

   Endpoint	기능
   User lookup	사용자 이름 또는 ID로 사용자 프로필 가져오기
   Post lookup	ID로 게시물 가져오기
   Recent search	최근 7일 동안의 포스트 검색

3. 요청 보내기

   cURL, Postman 또는 선호하는 HTTP 클라이언트를 사용하세요:

   # 사용자 이름으로 사용자 조회
   curl "https://api.x.com/2/users/by/username/xdevelopers" \
     -H "Authorization: Bearer $BEARER_TOKEN"
   
4. 응답 파싱

   응답은 JSON 형식입니다. 주요 데이터는 data 필드에 있습니다:

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

---

​

필드를 사용해 더 많은 데이터 요청하기

기본적으로 엔드포인트는 최소한의 필드만 반환합니다. 추가 데이터를 요청하려면 fields 파라미터를 사용하세요:

curl "https://api.x.com/2/users/by/username/xdevelopers?user.fields=created_at,description,public_metrics" \
  -H "Authorization: Bearer $BEARER_TOKEN"

응답:

{
  "data": {
    "id": "2244994945",
    "name": "X Developers",
    "username": "xdevelopers",
    "created_at": "2013-12-14T04:35:55.000Z",
    "description": "X Developer Platform의 목소리",
    "public_metrics": {
      "followers_count": 570842,
      "following_count": 2048,
      "tweet_count": 14052,
      "listed_count": 1672
    }
  }
}

필드에 대해 자세히 알아보기 →

---

​

추가 예제

게시물 조회

curl "https://api.x.com/2/tweets/1460323737035677698?tweet.fields=created_at,public_metrics" \
  -H "Authorization: Bearer $BEARER_TOKEN"

최근 포스트 검색

curl "https://api.x.com/2/tweets/search/recent?query=from:xdevelopers&tweet.fields=created_at" \
  -H "Authorization: Bearer $BEARER_TOKEN"

사용자의 포스트 가져오기

curl "https://api.x.com/2/users/2244994945/tweets?max_results=5" \
  -H "Authorization: Bearer $BEARER_TOKEN"

---

​

cURL 대신 코드 사용하기

Python

import requests

bearer_token = "YOUR_BEARER_TOKEN"
url = "https://api.x.com/2/users/by/username/xdevelopers"

headers = {"Authorization": f"Bearer {bearer_token}"}
response = requests.get(url, headers=headers)

print(response.json())

JavaScript

const bearerToken = "YOUR_BEARER_TOKEN";
const url = "https://api.x.com/2/users/by/username/xdevelopers";

fetch(url, {
  headers: { Authorization: `Bearer ${bearerToken}` }
})
  .then(res => res.json())
  .then(data => console.log(data));

Official SDKs

실서비스(프로덕션) 환경에서는 공식 SDK 사용을 권장합니다:

• Python SDK
• TypeScript SDK

공식 SDK는 인증, 페이지네이션, 요청 속도 제한(rate limiting)을 자동으로 처리합니다.

---

​

테스트용 도구

Postman

제공하는 컬렉션을 사용해 API를 시각적으로 테스트할 수 있습니다.

샘플 코드

여러 언어로 된 예제 코드를 제공합니다.

API 참조 문서

엔드포인트에 대한 전체 문서를 제공합니다.

---

​

문제 해결

401 Unauthorized

• Bearer 토큰이 올바른지 확인하세요
• 토큰이 재발급되거나 변경되지 않았는지 확인하세요
• Authorization 헤더 형식을 확인하세요: Bearer YOUR_TOKEN

403 Forbidden

• App이 이 엔드포인트에 대한 액세스 권한이 없을 수 있습니다
• 일부 엔드포인트는 사용자 컨텍스트 인증(OAuth 1.0a 또는 2.0)을 요구합니다
• 개발자 콘솔에서 App의 권한을 확인하세요

429 Too Many Requests

• 요청 한도(rate limit)에 도달했습니다
• 다시 시도할 시점을 확인하려면 x-rate-limit-reset 헤더를 확인하세요
• 코드에서 지수 백오프를 구현하세요

전체 오류 참조 →

---

​

다음 단계

인증 알아보기

사용자 컨텍스트 요청에 사용하는 OAuth를 이해하세요.

엔드포인트 살펴보기

무엇을 구축할 수 있는지 알아보세요.

SDK 사용하기

공식 라이브러리로 더 빠르게 개발하세요.

무언가 만들어 보기

무엇을 만들지에 대한 아이디어를 얻어보세요.