> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# X API Rate Limit

> Post, User, 검색, 스트림, DM에 대한 endpoint별 X API v2 rate limit과 x-rate-limit 응답 헤더를 읽고 429를 처리하는 방법.

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](https://console.x.com)에서도 확인할 수 있습니다.

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

### 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 응답을 받게 됩니다:

```json theme={null}
{
  "errors": [{
    "code": 88,
    "message": "Rate limit exceeded"
  }]
}
```

### 복구 전략

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

```python title="Example" lines wrap icon="python" theme={null}
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
```

***

## 모범 사례

<CardGroup cols={2}>
  <Card title="응답 캐싱" icon="database">
    반복 요청을 줄이려면 결과를 로컬에 저장하세요.
  </Card>

  <Card title="스트리밍 사용" icon="signal-stream">
    실시간 데이터의 경우 폴링 대신 filtered stream을 사용하세요.
  </Card>

  <Card title="헤더 모니터링" icon="gauge-high">
    한도 도달을 방지하려면 남은 요청을 추적하세요.
  </Card>

  <Card title="요청 분산" icon="clock">
    시간 창에 걸쳐 요청을 분산하세요.
  </Card>
</CardGroup>

***

## Rate limit vs. 청구

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

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

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

***

## Enterprise rate limit

Enterprise 고객은 맞춤 rate limit을 가집니다. 계정 관리자에게 문의하거나 [Enterprise 액세스를 신청](/enterprise/forms/enterprise-api-interest)하세요.

***

## 다음 단계

<CardGroup cols={2}>
  <Card title="오류 처리" icon="https://mintcdn.com/x-preview/jLbdFJYHCS9a6gmb/icons/xds/icon-warning.svg?fit=max&auto=format&n=jLbdFJYHCS9a6gmb&q=85&s=3760ceda7c43e1ffbd9f8b7ccbf83cca" href="/x-api/fundamentals/response-codes-and-errors" width="24" height="24" data-path="icons/xds/icon-warning.svg">
    429 및 기타 오류를 처리하세요.
  </Card>

  <Card title="시작하기" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/getting-started/about-x-api" width="24" height="24" data-path="icons/xds/icon-rocket.svg">
    액세스 수준 및 기능에 대해 알아보세요.
  </Card>
</CardGroup>