---
document_id: agent.collection.task.reddit_search_posts_v1
schema_version: 2
parent_document_id: agent.querying
section: querying
---

<!-- Generated by scripts.build_agent_guide; do not edit. -->

# Search posts / 搜索帖子

Search Reddit 帖子 by keyword, paged by cursor.

按关键词搜索 Reddit 帖子，按游标翻页。

Task / 任务: `reddit_search_posts_v1`
Platform / 平台: Reddit / Reddit
Billing / 计费: 2 Credits per successful task / 每个成功任务 2 Credits
Estimate / 估价: call `estimate_collection`; start directly when `approval_required=false`, otherwise obtain approval for `upper_bound_credits`.
估价：调用 `estimate_collection`；`approval_required=false` 时直接启动，否则请用户确认 `upper_bound_credits`。

## Limitations / 限制

- 按游标翻页：把 next_cursor 原样传回 cursor。
- 跨页会重排，结果已按 id 去重；has_more 只反映上游是否还有下一页。
- sort 只接受 RELEVANCE、HOT、TOP、NEW、COMMENTS。

## Inputs / 输入

- `keyword` — Keyword / 关键词; kind=text; required=True; default=''; bounds=min_length=1, max_length=100
- `sort` — Sort / 排序; kind=select; required=False; default='RELEVANCE'; allowed=RELEVANCE, HOT, TOP, NEW, COMMENTS
- `time_range` — Time range / 时间范围; kind=select; required=False; default='all'; allowed=all, year, month, week, day, hour
- `cursor` — Cursor / 翻页游标; kind=cursor; required=False; default=''; bounds=max_length=4096

## Minimal call / 最小调用

`estimate_collection`

```json
{
  "task_query": "搜索 Reddit 上关于机器人吸尘器的帖子",
  "task_code": "reddit_search_posts_v1",
  "input": {
    "keyword": "robot vacuum"
  }
}
```


## Result and pagination / 结果与分页

- mode=cursor
- input: `cursor`; continuation: `data.has_more` → `data.next_cursor`

Only the fields listed below are part of the stable result contract. /
只有下方列出的字段属于稳定结果契约。

## Result fields / 结果字段

- `meta.request_id` — type=string; Asklear request identifier for tracing. / 用于追踪的 Asklear 请求 ID。
- `meta.api_name` — type=string; Executed collection operation name. / 实际执行的采集操作名称。
- `meta.latency_ms` — type=integer; Collection execution latency in milliseconds. / 采集执行耗时（毫秒）。
- `meta.credits_charged` — type=integer; Asklear user-side Credits settled for this task after completion. / 任务完成后 Asklear 用户侧实际结算的 Credits。
- `data.items` — type=array<object>; Projected public items for this task. / 本任务投影后的公开条目。
- `data.item_count` — type=integer; Number of returned items. / 本次返回的条目数。
- `data.items[].post_id` — type=scalar|null; Post identifier, when available. / 帖子 ID（如有）。
- `data.items[].title` — type=scalar|null; Title, when available. / 标题（如有）。
- `data.items[].text` — type=scalar|null; Text content, when available. / 正文内容（如有）。
- `data.items[].url` — type=scalar|null; Public URL, when available. / 公开链接（如有）。
- `data.items[].permalink` — type=scalar|null; Permanent URL, when available. / 永久链接（如有）。
- `data.items[].published_at` — type=integer|null; Publication time, when available. / 发布时间（如有）。
- `data.items[].edited_at` — type=integer|null; Last edit time, when available. / 最后编辑时间（如有）。
- `data.items[].score` — type=scalar|null; Score, when available. / 评分（如有）。
- `data.items[].comment_count` — type=scalar|null; Comment count, when available. / 评论数（如有）。
- `data.items[].upvote_ratio` — type=scalar|null; Upvote ratio, when available. / 赞成票比例（如有）。
- `data.items[].domain` — type=scalar|null; Domain, when available. / 域名（如有）。
- `data.items[].language` — type=scalar|null; Language, when available. / 语言（如有）。
- `data.items[].is_nsfw` — type=scalar|null; Adult-content flag, when available. / 成人内容标记（如有）。
- `data.items[].is_spoiler` — type=scalar|null; Is spoiler, when available. / 是否剧透（如有）。
- `data.items[].is_locked` — type=scalar|null; Is locked, when available. / 是否锁定（如有）。
- `data.items[].author_id` — type=scalar|null; Author identifier, when available. / 作者 ID（如有）。
- `data.items[].author_name` — type=scalar|null; Author display name, when available. / 作者名称（如有）。
- `data.items[].subreddit_id` — type=scalar|null; Community identifier, when available. / 版块 ID（如有）。
- `data.items[].subreddit_name` — type=scalar|null; Community name, when available. / 版块名称（如有）。
- `data.items[].thumbnail` — type=scalar|null; Thumbnail, when available. / 缩略图（如有）。
- `data.has_more` — type=boolean; Whether a continuation is available. / 是否还有下一页。
- `data.next_cursor` — type=string|null; Cursor for the next page, or null. / 下一页游标；无下一页时为 null。

Use `list_collection_tasks` as the runtime authority, then `describe_collection_task` for one task's full input contract, examples and limits. Collection access is entitlement-gated. /
以 `list_collection_tasks` 返回为运行时准据，再用 `describe_collection_task` 取单个任务的完整入参契约、示例与限制；采集能力受 entitlement 控制。