X API Rate Limit

Rate limit은 각 endpoint에 대해 만들 수 있는 요청 수를 제어합니다. 한도를 초과하면 창이 재설정될 때까지 429 오류가 발생합니다.

Rate limit 작동 방식

개념	설명
시간 창	일반적으로 15분 또는 24시간
사용자별 한도	OAuth 1.0a 또는 OAuth 2.0 사용자 토큰에 적용
앱별 한도	Bearer Token(앱 전용)에 적용
Endpoint별	각 endpoint에는 자체 한도가 있습니다

한도 확인

응답 헤더는 현재 rate limit 상태를 보여줍니다:

x-rate-limit-limit: 900
x-rate-limit-remaining: 847
x-rate-limit-reset: 1705420800

Header	설명
`x-rate-limit-limit`	허용된 최대 요청
`x-rate-limit-remaining`	창에서 남은 요청
`x-rate-limit-reset`	창이 재설정되는 Unix 타임스탬프

Rate limit 표

아래에서 각 endpoint의 rate limit을 확인하세요. 이러한 한도는 Developer Console에서도 확인할 수 있습니다.

별도로 표시된 경우(예: “/24hrs” 또는 “/sec”)를 제외하고 한도는 15분당으로 표시됩니다.

Posts (endpoint 25개)

Tweet 조회

Method	Endpoint	앱별	사용자별
GET	`/2/tweets`	3,500/15min	5,000/15min
GET	`/2/tweets/:id`	450/15min	900/15min

Recent search

Method	Endpoint	앱별	사용자별	Notes
GET	`/2/tweets/search/recent`	450/15min	300/15min	10 default, 100 max results; 512 query length

Full-archive search

Method	Endpoint	앱별	사용자별	Notes
GET	`/2/tweets/search/all`	1/sec, 300/15min	1/sec	10 default, 500 max results; 1024 query length

Post 카운트

Method	Endpoint	앱별	사용자별	Notes
GET	`/2/tweets/counts/recent`	300/15min	—	512 query length
GET	`/2/tweets/counts/all`	300/15min	—	1024 query length

Filtered stream

Method	Endpoint	앱별	사용자별	Notes
GET	`/2/tweets/search/stream`	50/15min	—	1 connection; 1000 rules; 1024 rule length; 250 posts/sec
GET	`/2/tweets/search/stream/rules`	450/15min	—	1 connection; 1000 rules; 1024 rule length
POST	`/2/tweets/search/stream/rules`	100/15min	—	1 connection; 1000 rules; 1024 rule length

Post 관리

Method	Endpoint	앱별	사용자별
POST	`/2/tweets`	10,000/24hrs	100/15min
DELETE	`/2/tweets/:id`	—	50/15min

타임라인

Method	Endpoint	앱별	사용자별
GET	`/2/users/:id/tweets`	10,000/15min	900/15min
GET	`/2/users/:id/mentions`	450/15min	300/15min
GET	`/2/users/:id/timelines/reverse_chronological`	—	180/15min

좋아요 조회

Method	Endpoint	앱별	사용자별
GET	`/2/tweets/:id/liking_users`	75/15min	75/15min
GET	`/2/users/:id/liked_tweets`	75/15min	75/15min

좋아요 관리

Method	Endpoint	앱별	사용자별
POST	`/2/users/:id/likes`	—	50/15min, 1,000/24hrs
DELETE	`/2/users/:id/likes/:tweet_id`	—	50/15min, 1,000/24hrs

Retweet 조회

Method	Endpoint	앱별	사용자별	Notes
GET	`/2/tweets/:id/retweeted_by`	75/15min	75/15min	—
GET	`/2/tweets/:id/quote_tweets`	75/15min	75/15min	—
GET	`/2/users/reposts_of_me`	—	75/15min	100 max results

Retweet 관리

Method	Endpoint	앱별	사용자별
POST	`/2/users/:id/retweets`	—	50/15min
DELETE	`/2/users/:id/retweets/:tweet_id`	—	50/15min

답글 숨기기

Method	Endpoint	앱별	사용자별
PUT	`/2/tweets/:tweet_id/hidden`	—	50/15min

Users (endpoint 14개)

User 조회

Method	Endpoint	앱별	사용자별
GET	`/2/users`	300/15min	900/15min
GET	`/2/users/:id`	300/15min	900/15min
GET	`/2/users/by`	300/15min	900/15min
GET	`/2/users/by/username/:username`	300/15min	900/15min
GET	`/2/users/me`	—	75/15min

사용자 검색

Method	Endpoint	앱별	사용자별
GET	`/2/users/search`	300/15min	900/15min

팔로우 조회

Method	Endpoint	앱별	사용자별
GET	`/2/users/:id/following`	300/15min	300/15min
GET	`/2/users/:id/followers`	300/15min	300/15min

팔로우 관리

Method	Endpoint	앱별	사용자별
POST	`/2/users/:id/following`	—	50/15min
DELETE	`/2/users/:source_user_id/following/:target_user_id`	—	50/15min

차단 조회

Method	Endpoint	앱별	사용자별
GET	`/2/users/:id/blocking`	—	15/15min

뮤트 조회

Method	Endpoint	앱별	사용자별
GET	`/2/users/:id/muting`	—	15/15min

뮤트 관리

Method	Endpoint	앱별	사용자별
POST	`/2/users/:id/muting`	—	50/15min
DELETE	`/2/users/:source_user_id/muting/:target_user_id`	—	50/15min

Spaces (endpoint 6개)

Space 조회

Method	Endpoint	앱별	사용자별
GET	`/2/spaces/:id`	300/15min	300/15min
GET	`/2/spaces`	300/15min	300/15min
GET	`/2/spaces/:id/tweets`	300/15min	300/15min
GET	`/2/spaces/by/creator_ids`	300/15min, 1/sec	300/15min, 1/sec
GET	`/2/spaces/:id/buyers`	300/15min	300/15min

Space 검색

Method	Endpoint	앱별	사용자별
GET	`/2/spaces/search`	300/15min	300/15min

Direct Messages (endpoint 8개)

Direct Message 조회

Method	Endpoint	앱별	사용자별
GET	`/2/dm_events`	—	15/15min
GET	`/2/dm_events/:id`	—	15/15min
GET	`/2/dm_conversations/:dm_conversation_id/dm_events`	—	15/15min
GET	`/2/dm_conversations/with/:participant_id/dm_events`	—	15/15min

Direct Message 관리

Method	Endpoint	앱별	사용자별
POST	`/2/dm_conversations`	1,440/24hrs	15/15min, 1,440/24hrs
POST	`/2/dm_conversations/with/:participant_id/messages`	1,440/24hrs	15/15min, 1,440/24hrs
POST	`/2/dm_conversations/:dm_conversation_id/messages`	1,440/24hrs	15/15min, 1,440/24hrs
DELETE	`/2/dm_events/:id`	4,000/24hrs	300/15min, 1,500/24hrs

Lists (endpoint 14개)

List 조회

Method	Endpoint	앱별	사용자별
GET	`/2/lists/:id`	75/15min	75/15min
GET	`/2/users/:id/owned_lists`	15/15min	15/15min

List Tweet 조회

Method	Endpoint	앱별	사용자별
GET	`/2/lists/:id/tweets`	900/15min	900/15min

List 멤버 조회

Method	Endpoint	앱별	사용자별
GET	`/2/lists/:id/members`	900/15min	900/15min
GET	`/2/users/:id/list_memberships`	75/15min	75/15min

List 관리

Method	Endpoint	앱별	사용자별
POST	`/2/lists`	—	300/15min
DELETE	`/2/lists/:id`	—	300/15min
PUT	`/2/lists/:id`	—	300/15min

List 멤버 관리

Method	Endpoint	앱별	사용자별
POST	`/2/lists/:id/members`	—	300/15min
DELETE	`/2/lists/:id/members/:user_id`	—	300/15min

List 팔로우 관리

Method	Endpoint	앱별	사용자별
POST	`/2/users/:id/followed_lists`	—	50/15min
DELETE	`/2/users/:id/followed_lists/:list_id`	—	50/15min

고정된 List

Method	Endpoint	앱별	사용자별
GET	`/2/users/:id/pinned_lists`	15/15min	15/15min
POST	`/2/users/:id/pinned_lists`	—	50/15min
DELETE	`/2/users/:id/pinned_lists/:list_id`	—	50/15min

Bookmarks (endpoint 5개)

Bookmark 조회

Method	Endpoint	앱별	사용자별
GET	`/2/users/:id/bookmarks`	—	180/15min
GET	`/2/users/:id/bookmarks/folders`	50/15min	50/15min
GET	`/2/users/:id/bookmarks/folders/:folder_id`	50/15min	50/15min

Bookmark 관리

Method	Endpoint	앱별	사용자별
POST	`/2/users/:id/bookmarks`	—	50/15min
DELETE	`/2/users/:id/bookmarks/:tweet_id`	—	50/15min

Compliance (endpoint 3개)

배치 컴플라이언스

Method	Endpoint	앱별	사용자별
POST	`/2/compliance/jobs`	150/15min	—
GET	`/2/compliance/jobs/:job_id`	150/15min	—
GET	`/2/compliance/jobs`	150/15min	—

Usage (endpoint 1개)

Method	Endpoint	앱별	사용자별
GET	`/2/usage/tweets`	50/15min	—

Trends (endpoint 2개)

개인화된 트렌드

Method	Endpoint	앱별	사용자별
GET	`/2/users/personalized_trends`	200/24hrs, 200/15min	100/24hrs, 10/15min

WOEID별 트렌드

Method	Endpoint	앱별	사용자별
GET	`/2/trends/by/woeid/:id`	75/15min	—

Communities (endpoint 2개)

Method	Endpoint	앱별	사용자별	Notes
GET	`/2/communities/:id`	300/15min	300/15min	—
GET	`/2/communities/search`	300/15min	300/15min	100 max results

Analytics (endpoint 1개)

Method	Endpoint	앱별	사용자별
GET	`/2/tweets/analytics`	300/15min	300/15min

Media (endpoint 8개)

Method	Endpoint	앱별	사용자별
POST	`/2/media/upload`	50,000/24hrs	500/15min
GET	`/2/media/upload`	100,000/24hrs	1,000/15min
POST	`/2/media/upload/initialize`	180,000/24hrs	1,875/15min
POST	`/2/media/upload/:id/append`	180,000/24hrs	1,875/15min
POST	`/2/media/upload/:id/finalize`	180,000/24hrs	1,875/15min
POST	`/2/media/metadata`	50,000/24hrs	500/15min
POST	`/2/media/subtitles`	10,000/24hrs	100/15min
DELETE	`/2/media/subtitles`	10,000/24hrs	100/15min

Activity 및 Webhook

Method	Endpoint	앱별	사용자별	Notes
GET	`/2/activity/stream`	450/15min	—	2 connections; 250 posts/sec
POST	`/2/activity/subscriptions`	500/15min	—	—
GET	`/2/activity/subscriptions`	500/15min	—	—
PUT	`/2/activity/subscriptions/:subscription_id`	500/15min	—	—
DELETE	`/2/activity/subscriptions/:subscription_id`	500/15min	—	—
POST	`/2/webhooks`	450/15min	—	—
GET	`/2/webhooks`	450/15min	—	—
PUT	`/2/webhooks/:webhook_id`	450/15min	—	—
DELETE	`/2/webhooks/:webhook_id`	450/15min	—	—
POST	`/2/webhooks/replay`	100/15min	—	—

기타 endpoint

Method	Endpoint	앱별	사용자별
GET	`/2/tweets/sample10/stream`	100/15min	—
GET	`/2/news/:id`	200/15min	—
GET	`/2/news/search`	200/15min	200/15min
POST	`/2/users/:id/dm/block`	25/15min, 1,000/24hrs	10/15min, 400/24hrs
POST	`/2/users/:id/dm/unblock`	25/15min, 1,000/24hrs	10/15min, 400/24hrs
GET	`/2/users/by/username/:username/tweets`	1,500/15min	900/15min
GET	`/2/users/by/username/:username/mentions`	450/15min	180/15min
GET	`/2/users/:id/following/spaces`	300/15min	300/15min
GET	`/2/tweets/:id/retweets`	75/15min	75/15min
DELETE	`/2/connections/all`	25/15min	25/15min

Rate limit 처리

Rate limit에 도달하면 429 응답을 받게 됩니다:

{
  "errors": [{
    "code": 88,
    "message": "Rate limit exceeded"
  }]
}

복구 전략

창이 재설정되는 시점은 x-rate-limit-reset을 확인하세요
재시도하기 전에 그 시간까지 기다리세요
필요하면 지수 백오프를 사용하세요

Example

import time

def make_request_with_backoff(url, headers):
    response = requests.get(url, headers=headers)
    
    if response.status_code == 429:
        reset_time = int(response.headers.get('x-rate-limit-reset', 0))
        wait_time = max(reset_time - time.time(), 60)
        time.sleep(wait_time)
        return make_request_with_backoff(url, headers)
    
    return response

모범 사례

응답 캐싱

반복 요청을 줄이려면 결과를 로컬에 저장하세요.

스트리밍 사용

실시간 데이터의 경우 폴링 대신 filtered stream을 사용하세요.

헤더 모니터링

한도 도달을 방지하려면 남은 요청을 추적하세요.

요청 분산

시간 창에 걸쳐 요청을 분산하세요.

Rate limit vs. 청구

Rate limit과 청구는 별개입니다:

개념	목적
Rate limit	시스템 안정성을 위해 요청 빈도 제어
사용량 청구	조회된 데이터에 대한 청구(사용량 기반)

Rate limit 이내에 있어도 사용 비용이 발생할 수 있으며, 추가 비용 없이 rate limit에 도달할 수도 있습니다.

Enterprise rate limit

Enterprise 고객은 맞춤 rate limit을 가집니다. 계정 관리자에게 문의하거나 Enterprise 액세스를 신청하세요.

​Rate limit 작동 방식

​한도 확인

​Rate limit 표

​Posts (endpoint 25개)

​Tweet 조회

​Recent search

​Full-archive search

​Post 카운트

​Filtered stream

​Post 관리

​타임라인

​좋아요 조회

​좋아요 관리

​Retweet 조회

​Retweet 관리

​답글 숨기기

​Users (endpoint 14개)

​User 조회

​사용자 검색

​팔로우 조회

​팔로우 관리

​차단 조회

​뮤트 조회

​뮤트 관리

​Spaces (endpoint 6개)

​Space 조회

​Space 검색

​Direct Messages (endpoint 8개)

​Direct Message 조회

​Direct Message 관리

​Lists (endpoint 14개)

​List 조회

​List Tweet 조회

​List 멤버 조회

​List 관리

​List 멤버 관리

​List 팔로우 관리

​고정된 List

​Bookmarks (endpoint 5개)

​Bookmark 조회

​Bookmark 관리

​Compliance (endpoint 3개)

​배치 컴플라이언스

​Usage (endpoint 1개)

​Trends (endpoint 2개)

​개인화된 트렌드

​WOEID별 트렌드

​Communities (endpoint 2개)

​Analytics (endpoint 1개)

​Media (endpoint 8개)

​Activity 및 Webhook

​기타 endpoint

​Rate limit 처리

​복구 전략

​모범 사례

응답 캐싱

스트리밍 사용

헤더 모니터링

요청 분산

​Rate limit vs. 청구

​Enterprise rate limit

​다음 단계

오류 처리

시작하기

Rate limit 작동 방식

한도 확인

Rate limit 표

Posts (endpoint 25개)

Tweet 조회

Recent search

Full-archive search

Post 카운트

Filtered stream

Post 관리

타임라인

좋아요 조회

좋아요 관리

Retweet 조회

Retweet 관리

답글 숨기기

Users (endpoint 14개)

User 조회

사용자 검색

팔로우 조회

팔로우 관리

차단 조회

뮤트 조회

뮤트 관리

Spaces (endpoint 6개)

Space 조회

Space 검색

Direct Messages (endpoint 8개)

Direct Message 조회

Direct Message 관리

Lists (endpoint 14개)

List 조회

List Tweet 조회

List 멤버 조회

List 관리

List 멤버 관리

List 팔로우 관리

고정된 List

Bookmarks (endpoint 5개)

Bookmark 조회

Bookmark 관리

Compliance (endpoint 3개)

배치 컴플라이언스

Usage (endpoint 1개)

Trends (endpoint 2개)

개인화된 트렌드

WOEID별 트렌드

Communities (endpoint 2개)

Analytics (endpoint 1개)

Media (endpoint 8개)

Activity 및 Webhook

기타 endpoint

Rate limit 처리

복구 전략

모범 사례

Rate limit vs. 청구

Enterprise rate limit

다음 단계