---
title: "Posts"
description: "列出 X 账号的最新帖子。"
---

```http
GET | POST /v1/x/posts
```

参数可以用 `GET` 的查询字符串发送，也可以用 `POST` 的 JSON 请求体发送，两者等价。

## 传入内容

| 传入 | 读取内容 | 说明 |
|---|---|---|
| `username` 或 `userId` | 该账号的最新帖子 | `userId` 可省去一次查询 |

每次调用只传一个来源。所有标识符也都接受页面 URL。

## 返回哪一个列表

未登录的 X 会给账号提供两种列表之一，页面的 `ext.order` 会说明是哪一种：

- `latest`：账号的帖子，按时间从新到旧，每页约 20 条，并附带用于下一页的 `cursor`。
- `popular`：对部分账号，X 改为提供其获赞最多的帖子，约 100 条一次返回，不按日期排序，也没有 `cursor`。

账号置顶的帖子出现在第一页最前面，标记为 `pinned: true`，之后的页面不再重复。每页条数由 X 决定，因此 `limit` 只是参考值。

## 参数

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `cursor` | string |  | Opaque cursor from the previous page's `cursor`. Pass it alone for the next page. |
| `limit` | integer 1–100 |  | Items per page, 1–100 — a hint only: X decides the page size (about 20, or ~100 for the most-liked list). |
| `userId` | string |  | Numeric user id. Pass it instead of a username to save the lookup. |
| `username` | string |  | @handle (with or without @), or the profile URL. |

## 请求

```bash tab="cURL"
curl "https://gateway.apinoa.com/v1/x/posts?username=nasa&limit=5" \
  -H "x-api-key: $APINOA_API_KEY"
```

```js tab="JavaScript"
const params = new URLSearchParams({ username: "nasa", limit: "5" });
const res = await fetch(`https://gateway.apinoa.com/v1/x/posts?${params}`, {
  headers: { "x-api-key": process.env.APINOA_API_KEY },
});
const { success, data, error } = await res.json();
```

```python tab="Python"
import os

import requests

res = requests.get(
    "https://gateway.apinoa.com/v1/x/posts",
    params={"username": "nasa", "limit": "5"},
    headers={"x-api-key": os.environ["APINOA_API_KEY"]},
)
body = res.json()
```

## 响应

在 `data` 中返回 [`Post`](/docs/api-reference/sns/response-schema#post) [`Page`](/docs/api-reference/sns/response-schema#page)。 真实响应的节选：数组只保留前几项，长文本已截断。

```json
{
  "success": true,
  "data": {
    "platform": "x",
    "items": [
      {
        "platform": "x",
        "id": "2113776971603689874",
        "url": "https://x.com/NASA/status/2113776971603689874",
        "author": {
          "platform": "x",
          "id": "11348282",
          "handle": "NASA",
          "displayName": "NASA",
          "url": "https://x.com/NASA",
          "avatarUrl": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB.jpg",
          "verified": true,
          "counts": {
            "followers": 92311241,
            "following": 115,
            "posts": 74453
          },
          "ext": {
            "blueVerified": true,
            "verifiedType": "Government"
          }
        },
        "text": "We are not slowing down. 🚀\n\nOur Artemis III mission will send four astronauts to low Earth orbit next year to test crit…",
        "createdAt": "2026-10-23T23:37:56.000Z",
        "lang": "en",
        "media": [
          {
            "type": "video",
            "url": "https://video.twimg.com/amplify_video/2113776813121941504/vid/avc1/1920x1080/oa29OYgVBG7qAyEB.mp4?tag=16",
            "thumbnailUrl": "https://pbs.twimg.com/media/HVWk812WIAAg_hz.jpg?name=orig",
            "width": 3840,
            "height": 2160,
            "durationSec": 59.893,
            "variants": [
              {
                "url": "https://video.twimg.com/amplify_video/2113776813121941504/pl/Sws2JLpHl8xdzMyH.m3u8?tag=16&v=ab6",
                "contentType": "application/x-mpegURL"
              },
              {
                "url": "https://video.twimg.com/amplify_video/2113776813121941504/vid/avc1/480x270/CK1pQpicyNC7ryVp.mp4?tag=16",
                "bitrate": 288000,
                "contentType": "video/mp4"
              }
            ]
          }
        ],
        "metrics": {
          "likes": 5396,
          "comments": 236,
          "views": 900353,
          "reposts": 680,
          "quotes": 59,
          "saves": 259
        },
        "entities": {
          "urls": [
            {
              "url": "https://go.nasa.gov/4jzartX",
              "displayUrl": "go.nasa.gov/4jzartX"
            },
            {
              "url": "https://go.nasa.gov/4zV3TLc",
              "displayUrl": "go.nasa.gov/4zV3TLc"
            }
          ]
        },
        "ext": {
          "conversationId": "2113776971603689874"
        },
        "pinned": true
      }
    ],
    "cursor": "LssW7FrvIb2W_z-EPjiVogYoj3-70ruy8A1hYTEVJNyV1xfWjamuub5cCUPOolr5oPAzKDidQINisvCy-drXkJvvPVGst8_JWWGhxGuKr_D5Ykq9D8H5vhr…",
    "ext": {
      "order": "latest"
    }
  }
}
```

## 错误

| 状态 | 代码 | 含义 |
|---|---|---|
| 400 | `INVALID_CURSOR` | 该 `cursor` 不是本操作返回的。请不带它重新开始。 |
| 400 | `INVALID_PARAMS` | 参数缺失、未知或超出范围。消息中会指出是哪一个。 |
| 401 | `UNAUTHORIZED` | 缺少 `x-api-key` 请求头，或密钥已吊销或未知。 |
| 402 | `INSUFFICIENT_BALANCE` | 余额不足以支付本次调用。请在控制台充值。 |
| 404 | `NOT_FOUND` | 账号、帖子或分组不存在，或为私密、已删除、有年龄限制。 |
| 429 | `MARKETPLACE_SATURATED` | 并发调用过多。请等待 `Retry-After` 秒后重试。 |
| 502 | `UPSTREAM_ERROR` | 平台返回了无法使用的内容。请退避后重试。 |

全部错误代码见 [Errors](/docs/errors)。失败的调用不计费。

## 价格

**Price** $0.001 per call, plus $0.001 for each extra call it makes — at most 1 more, so $0.002 in total. [List price](https://apinoa.com/en/pricing); the rate steps down above 1,000 calls a day.