x-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

X API: Query the X (Twitter) API v2 with curl

X API：使用curl查询X（Twitter）API v2

Overview

概述

Use curl commands to interact with the X (Twitter) API v2. This skill covers read-only, public endpoints that do not require an authenticated user context — things like looking up profiles, searching recent posts, and retrieving tweets.

Authentication assumption: The environment variable

X_BEARER_TOKEN

must already be set with a valid X API v2 Bearer Token. All commands below rely on it.

使用curl命令与X（Twitter）API v2进行交互。本技能涵盖无需用户上下文认证的只读公开端点——例如查询资料、搜索近期帖子、获取推文等操作。

认证前提： 环境变量

X_BEARER_TOKEN

必须已设置有效的X API v2 Bearer Token。以下所有命令均依赖该变量。

How to use

使用方法

All requests follow this pattern:

bash

curl "<endpoint_url>" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

For any endpoint that returns tweets, always include

note_tweet

tweet.fields

so long posts return full content.

所有请求遵循以下格式：

bash

curl "<endpoint_url>" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

对于任何返回推文的端点，请务必在

tweet.fields

中包含

note_tweet

，这样长帖子会返回完整内容。

Examples

示例

Get a user profile

获取用户资料

bash

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

bash

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

Get a user profile with additional fields

获取包含额外字段的用户资料

bash

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

Common

user.fields

created_at

description

entities

id

location

name

pinned_tweet_id

profile_image_url

protected

public_metrics

url

username

verified

withheld

bash

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

常用

user.fields

字段：

created_at

description

entities

id

location

name

pinned_tweet_id

profile_image_url

protected

public_metrics

url

username

verified

withheld

。

Look up a post by ID

通过ID查询帖子

bash

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

Common

tweet.fields

note_tweet

attachments

author_id

conversation_id

created_at

entities

id

in_reply_to_user_id

lang

public_metrics

referenced_tweets

source

text

withheld

bash

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

常用

tweet.fields

字段：

note_tweet

attachments

author_id

conversation_id

created_at

entities

id

in_reply_to_user_id

lang

public_metrics

referenced_tweets

source

text

withheld

。

Search recent posts

搜索近期帖子

bash

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

The

query

parameter supports the full X search query syntax. Examples:

```
from:username
```
— posts from a specific user
```
to:username
```
— replies to a specific user
```
"exact phrase"
```
— posts containing an exact phrase
```
keyword1 keyword2
```
— posts containing both keywords
```
keyword1 OR keyword2
```
— posts containing either keyword
```
#hashtag
```
— posts with a specific hashtag
```
has:media
```
— posts that contain media
```
has:links
```
— posts that contain links
```
lang:en
```
— posts in a specific language

bash

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

query

参数支持完整的X搜索语法。示例：

```
from:username
```
— 特定用户发布的帖子
```
to:username
```
— 回复特定用户的帖子
```
"exact phrase"
```
— 包含精确短语的帖子
```
keyword1 keyword2
```
— 同时包含两个关键词的帖子
```
keyword1 OR keyword2
```
— 包含任意一个关键词的帖子
```
#hashtag
```
— 包含特定话题标签的帖子
```
has:media
```
— 包含媒体内容的帖子
```
has:links
```
— 包含链接的帖子
```
lang:en
```
— 特定语言的帖子

Get a user's posts

获取用户发布的帖子

bash

curl "https://api.x.com/2/users/2244994945/tweets?max_results=5&tweet.fields=note_tweet" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

You can add more

tweet.fields

max_results

(5-100), and pagination tokens to customize the response, but always keep

note_tweet

included.

bash

curl "https://api.x.com/2/users/2244994945/tweets?max_results=5&tweet.fields=note_tweet" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

你可以添加更多

tweet.fields

、

max_results

（取值范围5-100）和分页令牌来自定义响应，但请务必保留

note_tweet

字段。

Get a user's mentions

获取用户的提及帖子

bash

curl "https://api.x.com/2/users/2244994945/mentions?max_results=5&tweet.fields=note_tweet,created_at,author_id" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

bash

curl "https://api.x.com/2/users/2244994945/mentions?max_results=5&tweet.fields=note_tweet,created_at,author_id" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

Look up multiple users by username

通过用户名批量查询用户

bash

curl "https://api.x.com/2/users/by?usernames=xdevelopers,twitterdev&user.fields=description,public_metrics" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

bash

curl "https://api.x.com/2/users/by?usernames=xdevelopers,twitterdev&user.fields=description,public_metrics" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

Get tweet counts for a search query

获取搜索查询的推文数量

bash

curl "https://api.x.com/2/tweets/counts/recent?query=from:xdevelopers" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

Returns the count of tweets matching the query, grouped by time period.

bash

curl "https://api.x.com/2/tweets/counts/recent?query=from:xdevelopers" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

返回匹配查询条件的推文数量，按时间段分组统计。

Get a user's followers

获取用户的关注者

bash

curl "https://api.x.com/2/users/2244994945/followers?max_results=10&user.fields=description,public_metrics" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

bash

curl "https://api.x.com/2/users/2244994945/followers?max_results=10&user.fields=description,public_metrics" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

Get accounts a user is following

获取用户关注的账号

bash

curl "https://api.x.com/2/users/2244994945/following?max_results=10&user.fields=description,public_metrics" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

bash

curl "https://api.x.com/2/users/2244994945/following?max_results=10&user.fields=description,public_metrics" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

Look up a list and its members

查询列表及其成员

bash

undefined

bash

undefined

Get list details

获取列表详情

curl "https://api.x.com/2/lists/84839422"
-H "Authorization: Bearer $X_BEARER_TOKEN"

Get list members

获取列表成员

curl "https://api.x.com/2/lists/84839422/members?user.fields=description,public_metrics"
-H "Authorization: Bearer $X_BEARER_TOKEN"

undefined

curl "https://api.x.com/2/lists/84839422/members?user.fields=description,public_metrics"
-H "Authorization: Bearer $X_BEARER_TOKEN"

undefined

Tips

提示

To find a user's numeric ID (needed for some endpoints), first look them up by username, then use the
```
id
```
field from the response.
Use
```
expansions
```
to include related objects in the response. For example,
```
expansions=author_id
```
on a tweet lookup will include the author's user object.
Pagination: When results span multiple pages, the response includes a
```
next_token
```
field. Pass it as
```
pagination_token
```
in the next request.
Rate limits vary by endpoint. If you receive a 429 response, wait before retrying.

若要获取用户的数字ID（部分端点需要），请先通过用户名查询用户，然后从响应中提取
```
id
```
字段。
使用
```
expansions
```
参数可在响应中包含关联对象。例如，在推文查询中添加
```
expansions=author_id
```
会包含作者的用户对象。
分页：当结果跨多页时，响应会包含
```
next_token
```
字段。将其作为
```
pagination_token
```
参数传入下一次请求即可。
不同端点的速率限制不同。若收到429响应，请等待后再重试。

API Reference

API参考

Full OpenAPI specification: https://api.x.com/2/openapi.json

完整OpenAPI规范：https://api.x.com/2/openapi.json

Authentication

认证

The

X_BEARER_TOKEN

environment variable must be set with a valid Bearer Token. This token provides app-only authentication, which grants access to public read-only endpoints.

To obtain a Bearer Token, create a project and app in the X Developer Portal and generate a Bearer Token from your app's "Keys and tokens" settings.

环境变量

X_BEARER_TOKEN

必须设置有效的Bearer Token。该令牌提供应用级认证，可访问只读公开端点。

要获取Bearer Token，请在X开发者平台创建项目和应用，然后从应用的“密钥与令牌”设置中生成Bearer Token。