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

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

# Search posts via API / 通过 API 搜索推文

Search X (Twitter) posts with a query and optional public sort filter.

使用查询词和可选的公开排序筛选搜索 X（推特）推文。

Task / 任务: `twitter_search_posts_api_v1`
Platform / 平台: X (Twitter) / X（推特）
Billing / 计费: 2 Credits per successful task / 每个成功任务 2 Credits
Access / 调用方式: this source is available through the Search API only; call `POST /v1/search` with `source`, then read `GET /v1/search/{job_id}`. It is not listed by `list_collection_tasks` and `describe_collection_task` does not answer for it.
调用方式：该来源仅通过 Search API 提供；用 `source` 调用 `POST /v1/search`，再用 `GET /v1/search/{job_id}` 读取结果。它不出现在 `list_collection_tasks` 中，`describe_collection_task` 也不返回它。

## Limitations / 限制

- 要取某条推文的详情用 `twitter_tweet_detail_v1`。
- 首次响应的 pagination.next_page_token 是 asklear-search-cursor-v1. 开头的不透明 Search 令牌；续页原样放入 page_token，保持 search_mode、query、filters 和 page_size 不变。令牌最长 4096 个 ASCII 字符，有效期 24 小时；无效、过期或错绑令牌返回 invalid_query。不要发送上游原始续页值；page 应省略或保持为 1，其他 page 值和 page_size 会被拒绝。新 source=twitter 是增量新增的 Search 能力，不替代原有 twitter_search_posts_v1 Collection 任务；两者的请求与续页契约相互隔离。twitter_search_posts_api_v1 只通过 /v1/search 使用，不列在普通 Collection 任务列表中。

## Inputs / 输入

- `query` — Query / 搜索词; kind=text; required=True; default=''; bounds=min_length=1, max_length=100
- `filters.sort` — Sort / 排序; kind=select; required=False; default='relevance'; allowed=relevance, latest
- `page_token` — Page token / 翻页令牌; kind=token; required=False; default=''; bounds=max_length=4096

## Minimal call / 最小调用

`search`

```json
{
  "source": "twitter",
  "query": "搜索 X 上关于机器人吸尘器的推文"
}
```


## Result and pagination / 结果与分页

- 分页方式：游标翻页。`page_token` 传入，下一页用 `pagination.next_page_token` 传回。

Search results are returned under `data.items`, with page state under `data.pagination`. /
Search 结果位于 `data.items`，分页状态位于 `data.pagination`。

Only the fields listed below are part of this source's stable Search result contract. /
只有下方列出的字段属于此来源的稳定 Search 结果契约。

## Result fields / 结果字段

- `data.items` — type=array<object>; Public Search results returned by this page. / 本页返回的公开 Search 结果。
- `data.items[].entity_id` — type=string; Stable public identifier for the result. / 结果的稳定公开标识。
- `data.items[].title` — type=string|null; No title in this phase; the unified field remains nullable string. / 本阶段没有标题；统一结果字段保留为可空字符串。
- `data.items[].url` — type=string|null; No reliable public URL in this phase; the unified field remains nullable string. / 本阶段没有可靠的公开 URL；统一结果字段保留为可空字符串。
- `data.items[].snippet` — type=string|null; Public text snippet, populated from the post text. / 由推文正文填充的来源无关文本摘要。
- `data.items[].text` — type=string|null; Post text when supplied. / 推文正文（如有）。
- `data.items[].published_at` — type=integer|null; Publication time as Unix seconds. / 以 Unix 秒表示的发布时间。
- `data.items[].like_count` — type=integer|null; Like count. / 点赞数。
- `data.items[].repost_count` — type=integer|null; Repost count. / 转发数。
- `data.items[].comment_count` — type=integer|null; Comment count, mapped from reply_count. / 评论数，由上游 reply_count 映射而来。
- `data.items[].view_count` — type=integer|null; View count. / 浏览数。
- `data.items[].author_id` — type=string|null; Author identifier. / 作者 ID。
- `data.items[].author_name` — type=string|null; Author display name. / 作者显示名称。
- `data.pagination.has_more` — type=boolean; Whether another public Search page is available. / 是否还有下一页公开 Search 结果。
- `data.pagination.next_page_token` — type=string|null; Opaque continuation token for page_token; tokens start with asklear-search-cursor-v1. / 传回 page_token 的不透明续页令牌；令牌以 asklear-search-cursor-v1. 开头。

This source is published by the Search API. Use `POST /v1/search` and `GET /v1/search/{job_id}`; it has no generic Collection entry point. /
该来源由 Search API 发布，请使用 `POST /v1/search` 与 `GET /v1/search/{job_id}`；它没有通用采集入口。