Back to Details

x-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

X API

X API

Programmatic interaction with X (Twitter) for posting, reading, searching, and analytics.
通过编程方式与X（Twitter）交互，实现发布、读取、搜索及数据分析功能。

When to Activate

适用场景

  • User wants to post tweets or threads programmatically
  • Reading timeline, mentions, or user data from X
  • Searching X for content, trends, or conversations
  • Building X integrations or bots
  • Analytics and engagement tracking
  • User says "post to X", "tweet", "X API", or "Twitter API"
  • 用户需要以编程方式发布单条推文或线程推文
  • 从X读取时间线、提及内容或用户数据
  • 在X上搜索内容、趋势或对话
  • 构建X集成应用或机器人
  • 数据分析与互动追踪
  • 用户提及“发布到X”、“发推文”、“X API”或“Twitter API”时

Authentication

认证方式

OAuth 2.0 Bearer Token (App-Only)

OAuth 2.0 Bearer Token（仅应用级）

Best for: read-heavy operations, search, public data.
bash
undefined
最适用于：读密集型操作、搜索、公开数据获取。
bash
undefined

Environment setup

Environment setup

export X_BEARER_TOKEN="your-bearer-token"

```python
import os
import requests

bearer = os.environ["X_BEARER_TOKEN"]
headers = {"Authorization": f"Bearer {bearer}"}
export X_BEARER_TOKEN="your-bearer-token"

```python
import os
import requests

bearer = os.environ["X_BEARER_TOKEN"]
headers = {"Authorization": f"Bearer {bearer}"}

Search recent tweets

Search recent tweets

resp = requests.get( "https://api.x.com/2/tweets/search/recent", headers=headers, params={"query": "claude code", "max_results": 10} ) tweets = resp.json()
undefined
resp = requests.get( "https://api.x.com/2/tweets/search/recent", headers=headers, params={"query": "claude code", "max_results": 10} ) tweets = resp.json()
undefined

OAuth 1.0a (User Context)

OAuth 1.0a（用户上下文级）

Required for: posting tweets, managing account, DMs.
bash
undefined
适用于：发布推文、管理账户、私信功能。
bash
undefined

Environment setup — source before use

Environment setup — source before use

export X_API_KEY="your-api-key" export X_API_SECRET="your-api-secret" export X_ACCESS_TOKEN="your-access-token" export X_ACCESS_SECRET="your-access-secret"

```python
import os
from requests_oauthlib import OAuth1Session

oauth = OAuth1Session(
    os.environ["X_API_KEY"],
    client_secret=os.environ["X_API_SECRET"],
    resource_owner_key=os.environ["X_ACCESS_TOKEN"],
    resource_owner_secret=os.environ["X_ACCESS_SECRET"],
)
export X_API_KEY="your-api-key" export X_API_SECRET="your-api-secret" export X_ACCESS_TOKEN="your-access-token" export X_ACCESS_SECRET="your-access-secret"

```python
import os
from requests_oauthlib import OAuth1Session

oauth = OAuth1Session(
    os.environ["X_API_KEY"],
    client_secret=os.environ["X_API_SECRET"],
    resource_owner_key=os.environ["X_ACCESS_TOKEN"],
    resource_owner_secret=os.environ["X_ACCESS_SECRET"],
)

Core Operations

核心操作

Post a Tweet

发布单条推文

python
resp = oauth.post(
    "https://api.x.com/2/tweets",
    json={"text": "Hello from Claude Code"}
)
resp.raise_for_status()
tweet_id = resp.json()["data"]["id"]
python
resp = oauth.post(
    "https://api.x.com/2/tweets",
    json={"text": "Hello from Claude Code"}
)
resp.raise_for_status()
tweet_id = resp.json()["data"]["id"]

Post a Thread

发布线程推文

python
def post_thread(oauth, tweets: list[str]) -> list[str]:
    ids = []
    reply_to = None
    for text in tweets:
        payload = {"text": text}
        if reply_to:
            payload["reply"] = {"in_reply_to_tweet_id": reply_to}
        resp = oauth.post("https://api.x.com/2/tweets", json=payload)
        resp.raise_for_status()
        tweet_id = resp.json()["data"]["id"]
        ids.append(tweet_id)
        reply_to = tweet_id
    return ids
python
def post_thread(oauth, tweets: list[str]) -> list[str]:
    ids = []
    reply_to = None
    for text in tweets:
        payload = {"text": text}
        if reply_to:
            payload["reply"] = {"in_reply_to_tweet_id": reply_to}
        resp = oauth.post("https://api.x.com/2/tweets", json=payload)
        resp.raise_for_status()
        tweet_id = resp.json()["data"]["id"]
        ids.append(tweet_id)
        reply_to = tweet_id
    return ids

Read User Timeline

读取用户时间线

python
resp = requests.get(
    f"https://api.x.com/2/users/{user_id}/tweets",
    headers=headers,
    params={
        "max_results": 10,
        "tweet.fields": "created_at,public_metrics",
    }
)
python
resp = requests.get(
    f"https://api.x.com/2/users/{user_id}/tweets",
    headers=headers,
    params={
        "max_results": 10,
        "tweet.fields": "created_at,public_metrics",
    }
)

Search Tweets

搜索推文

python
resp = requests.get(
    "https://api.x.com/2/tweets/search/recent",
    headers=headers,
    params={
        "query": "from:affaanmustafa -is:retweet",
        "max_results": 10,
        "tweet.fields": "public_metrics,created_at",
    }
)
python
resp = requests.get(
    "https://api.x.com/2/tweets/search/recent",
    headers=headers,
    params={
        "query": "from:affaanmustafa -is:retweet",
        "max_results": 10,
        "tweet.fields": "public_metrics,created_at",
    }
)

Get User by Username

通过用户名获取用户信息

python
resp = requests.get(
    "https://api.x.com/2/users/by/username/affaanmustafa",
    headers=headers,
    params={"user.fields": "public_metrics,description,created_at"}
)
python
resp = requests.get(
    "https://api.x.com/2/users/by/username/affaanmustafa",
    headers=headers,
    params={"user.fields": "public_metrics,description,created_at"}
)

Upload Media and Post

上传媒体并发布

python
undefined
python
undefined

Media upload uses v1.1 endpoint

Media upload uses v1.1 endpoint

Step 1: Upload media

Step 1: Upload media

media_resp = oauth.post( "https://upload.twitter.com/1.1/media/upload.json", files={"media": open("image.png", "rb")} ) media_id = media_resp.json()["media_id_string"]
media_resp = oauth.post( "https://upload.twitter.com/1.1/media/upload.json", files={"media": open("image.png", "rb")} ) media_id = media_resp.json()["media_id_string"]

Step 2: Post with media

Step 2: Post with media

resp = oauth.post( "https://api.x.com/2/tweets", json={"text": "Check this out", "media": {"media_ids": [media_id]}} )
undefined
resp = oauth.post( "https://api.x.com/2/tweets", json={"text": "Check this out", "media": {"media_ids": [media_id]}} )
undefined

Rate Limits

速率限制

X API rate limits vary by endpoint, auth method, and account tier, and they change over time. Always:
  • Check the current X developer docs before hardcoding assumptions
  • Read 
    x-rate-limit-remaining
    and 
    x-rate-limit-reset
    headers at runtime
  • Back off automatically instead of relying on static tables in code
python
import time

remaining = int(resp.headers.get("x-rate-limit-remaining", 0))
if remaining < 5:
    reset = int(resp.headers.get("x-rate-limit-reset", 0))
    wait = max(0, reset - int(time.time()))
    print(f"Rate limit approaching. Resets in {wait}s")
X API的速率限制因接口、认证方式和账户等级而异，且会随时间变化。请始终遵循以下原则：
  • 在硬编码逻辑前，查阅最新的X开发者文档
  • 在运行时读取
    x-rate-limit-remaining
    和
    x-rate-limit-reset
    响应头
  • 自动进行退避处理，而非依赖代码中的静态限制表
python
import time

remaining = int(resp.headers.get("x-rate-limit-remaining", 0))
if remaining < 5:
    reset = int(resp.headers.get("x-rate-limit-reset", 0))
    wait = max(0, reset - int(time.time()))
    print(f"Rate limit approaching. Resets in {wait}s")

Error Handling

错误处理

python
resp = oauth.post("https://api.x.com/2/tweets", json={"text": content})
if resp.status_code == 201:
    return resp.json()["data"]["id"]
elif resp.status_code == 429:
    reset = int(resp.headers["x-rate-limit-reset"])
    raise Exception(f"Rate limited. Resets at {reset}")
elif resp.status_code == 403:
    raise Exception(f"Forbidden: {resp.json().get('detail', 'check permissions')}")
else:
    raise Exception(f"X API error {resp.status_code}: {resp.text}")
python
resp = oauth.post("https://api.x.com/2/tweets", json={"text": content})
if resp.status_code == 201:
    return resp.json()["data"]["id"]
elif resp.status_code == 429:
    reset = int(resp.headers["x-rate-limit-reset"])
    raise Exception(f"Rate limited. Resets at {reset}")
elif resp.status_code == 403:
    raise Exception(f"Forbidden: {resp.json().get('detail', 'check permissions')}")
else:
    raise Exception(f"X API error {resp.status_code}: {resp.text}")

Security

安全注意事项

  • Never hardcode tokens. Use environment variables or 
    .env
    files.
  • Never commit 
    .env
    files.     Add to 
    .gitignore
    .
  • Rotate tokens if exposed. Regenerate at developer.x.com.
  • Use read-only tokens when write access is not needed.
  • Store OAuth secrets securely — not in source code or logs.
  • 切勿硬编码令牌：使用环境变量或
    .env
    文件存储。
  • 切勿提交
    .env
    文件    ：将其添加到
    .gitignore
    中。
  • 令牌泄露后立即轮换：在developer.x.com重新生成。
  • 无需写入权限时使用只读令牌
  • 安全存储OAuth密钥：不要存储在源代码或日志中。

Integration with Content Engine

与内容引擎集成

Use 
content-engine
skill to generate platform-native content, then post via X API:
  1. Generate content with content-engine (X platform format)
  2. Validate length (280 chars for single tweet)
  3. Post via X API using patterns above
  4. Track engagement via public_metrics
使用
content-engine
技能生成平台原生内容，然后通过X API发布：
  1. 使用content-engine生成符合X平台格式的内容
  2. 验证内容长度（单条推文最多280字符）
  3. 使用上述模式通过X API发布
  4. 通过public_metrics追踪互动数据

Related Skills

相关技能

  • content-engine
    — Generate platform-native content for X
  • crosspost
    — Distribute content across X, LinkedIn, and other platforms
  • content-engine
    — 为X生成平台原生内容
  • crosspost
    — 在X、LinkedIn及其他平台分发内容