---
title: "Posts"
description: "从 Reddit 的任一列表获取帖子：某个用户、某个社区、一次搜索、指定 id，或热门信息流。"
---

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

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

## 传入内容

| 传入 | 读取内容 | 说明 |
|---|---|---|
| `username` | 某用户的帖子 | `sort`：`new`、`hot`、`top`、`controversial` |
| `community` | 某社区的帖子 | `sort`：`hot`、`new`、`top`、`rising`、`controversial` |
| `query` | 帖子搜索 | `sort`：`relevance`、`hot`、`top`、`new`、`comments`；加上 `community` 可在单个社区内搜索 |
| `ids` | 指定的帖子，单次调用最多 100 条 |  |
| 不传 | 热门信息流 | `country` 选择该国家的信息流；`sort`：`hot`、`new`、`top`、`rising` |

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

## 参数

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `community` | string |  | A community's posts: name (with or without r/) or URL. With `query`, narrows the search to it. |
| `country` | string |  | Default feed only: the country whose popular feed to read (ISO alpha-2). |
| `cursor` | string |  | Opaque cursor from the previous page's `cursor`. Pass it alone for the next page. |
| `ids` | string list |  | Specific posts: ids, fullnames (t3_…) or URLs, 1–100 in one call. |
| `limit` | integer 1–100 |  | Items per page, 1–100. |
| `period` | enum |  | Time window for sort top or controversial: hour, day, week, month, year or all. `hour` `day` `week` `month` `year` `all` |
| `query` | string |  | Search posts by keyword. |
| `sort` | enum |  | Order. username: new, hot, top, controversial · community: hot, new, top, rising, controversial · query: relevance, hot, top, new, comments · default feed: hot, new, top, rising. `hot` `new` `top` `rising` `controversial` `relevance` `comments` |
| `username` | string |  | A user's posts: username (with or without u/) or profile URL. |

## 请求

```bash tab="cURL"
curl "https://gateway.apinoa.com/v1/reddit/posts?community=technology&sort=top&period=week&limit=3" \
  -H "x-api-key: $APINOA_API_KEY"
```

```js tab="JavaScript"
const params = new URLSearchParams({ community: "technology", sort: "top", period: "week", limit: "3" });
const res = await fetch(`https://gateway.apinoa.com/v1/reddit/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/reddit/posts",
    params={"community": "technology", "sort": "top", "period": "week", "limit": "3"},
    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": "reddit",
    "items": [
      {
        "platform": "reddit",
        "id": "1xcg8as",
        "url": "https://www.reddit.com/r/technology/comments/1xcg8as/pure_arrogance_anger_in_finland_as_google/",
        "author": {
          "platform": "reddit",
          "handle": "WombatusMighty",
          "id": "5dv971n4"
        },
        "title": "‘Pure arrogance’: anger in Finland as Google illegally fells 250,000 trees for datacentre",
        "createdAt": "2026-10-22T11:41:24.000Z",
        "media": [],
        "metrics": {
          "comments": 1760
        },
        "linkPreview": {
          "url": "https://www.theguardian.com/environment/ng-interactive/2026/oct/22/finland-google-felling-trees-datacentre",
          "domain": "theguardian.com",
          "thumbnailUrl": "https://external-preview.redd.it/lFXQEMQFV6biLNRdb5GCAM5QH6hE_uoy07Oh_R_8gGY.jpeg?auto=webp&s=c2e26eb42ca63eb3b645fb216…"
        },
        "sensitive": false,
        "ext": {
          "fullname": "t3_1xcg8as",
          "score": 43304,
          "ups": 43304,
          "upvoteRatio": 0.97,
          "numCrossposts": 13,
          "awards": 0,
          "flair": "Society",
          "flairTextColor": "dark",
          "flairTemplateId": "80187d9a-a816-11e9-a79b-0ea66e3761e6",
          "kind": "link",
          "preview": {
            "source": {
              "url": "https://external-preview.redd.it/lFXQEMQFV6biLNRdb5GCAM5QH6hE_uoy07Oh_R_8gGY.jpeg?auto=webp&s=c2e26eb42ca63eb3b645fb216…",
              "width": 1200,
              "height": 630
            },
            "resolutions": [
              {
                "url": "https://external-preview.redd.it/lFXQEMQFV6biLNRdb5GCAM5QH6hE_uoy07Oh_R_8gGY.jpeg?width=108&crop=smart&auto=webp&s=207c…",
                "width": 108,
                "height": 56
              },
              {
                "url": "https://external-preview.redd.it/lFXQEMQFV6biLNRdb5GCAM5QH6hE_uoy07Oh_R_8gGY.jpeg?width=216&crop=smart&auto=webp&s=4886…",
                "width": 216,
                "height": 113
              }
            ],
            "enabled": false
          },
          "thumbnailUrl": "https://external-preview.redd.it/lFXQEMQFV6biLNRdb5GCAM5QH6hE_uoy07Oh_R_8gGY.jpeg?width=320&crop=smart&auto=webp&s=34e6…",
          "spoiler": false,
          "locked": false,
          "archived": false,
          "community": {
            "name": "technology",
            "id": "2qh16",
            "subscribers": 20595712,
            "type": "public"
          }
        }
      }
    ],
    "cursor": "VScWoTDcqFrJzxjNiQLrLiERD67YI2Z7BDybCfuuuw7Y1fj0I93Td2ktHpxH3S9F2oDtrW8sALbYe5XxRjBp60ZNmeeKaDtyJYHrrIWz545u3odld5-ZK0P…"
  }
}
```

## 错误

| 状态 | 代码 | 含义 |
|---|---|---|
| 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. [List price](https://apinoa.com/en/pricing); the rate steps down above 1,000 calls a day.

## 说明

- `period`（`hour` … `all`）在 `sort=top` 或 `sort=controversial` 时生效。