按关键词搜索推文

在 X/Twitter 上搜索匹配关键词或 hashtag 的推文

GET /listen/keyword

cURL

curl \
  -H "Authorization: Bearer API_KEY" \
  -H "x-twitter-oauth1-api-key: YOUR_TWITTER_API_KEY" \
  -H "x-twitter-oauth1-api-secret: YOUR_TWITTER_API_SECRET" \
  -X GET "https://api.ayrshare.com/api/listen/keyword?query=ayrshare%20OR%20%23socialmedia&platform=twitter&limit=15"

200: Success

{
  "status": "success",
  "platform": "twitter",
  "query": "ayrshare OR #socialmedia",
  "tweets": [
    {
      "id": "1234567890",
      "text": "Just discovered @ayrshare for managing social media APIs!",
      "createdAt": "2026-03-22T14:30:00.000Z",
      "user": {
        "id": "987654321",
        "name": "Jane Doe",
        "screenName": "janedoe",
        "profileImageUrl": "https://pbs.twimg.com/profile_images/..."
      },
      "metrics": {
        "retweetCount": 5,
        "favoriteCount": 12
      },
      "entities": {
        "hashtags": ["socialmedia"],
        "mentions": ["ayrshare"],
        "urls": []
      },
      "inReplyToStatusId": null,
      "isRetweet": false,
      "lang": "en"
    }
  ],
  "meta": {
    "pagination": {
      "hasMore": true,
      "next": "b26v89c19zqg8o3fpds7h...",
      "limit": 15
    }
  }
}

在 X/Twitter 上搜索匹配关键词、hashtag 以及高级搜索运算符的推文。返回标准化的推文数据,包括用户信息、互动指标和实体。

此端点要求为 X/Twitter 启用 Bring Your Own Keys (BYOK)。

重要限制

• 仅可获取最近约 7 天内的推文(X API 限制)。
• 默认每日调用上限为 25 次。
• 必须为 X/Twitter 提供 BYOK 密钥。

​

Header Parameters

​

Query Parameters

query · string · 必填

关键词搜索查询。支持 X/Twitter 搜索运算符(参见下表)。

示例:ayrshare、#socialmedia、ayrshare OR #socialmedia、from:ayrshare。

platform · string · 必填

必须为 twitter。

limit · integer · 默认值: 15

返回的最大推文数量。必须介于 10 到 100 之间。

sinceId · string

返回 ID 大于(晚于)该值的推文。适用于仅拉取自上次请求以来的新推文。

untilId · string

返回 ID 小于(早于)该值的推文。适用于向后翻页浏览结果。

next · string

上一次响应中 meta.pagination.next 返回的分页令牌。使用它可获取下一页结果。

​

搜索运算符

query 参数支持以下 X/Twitter 搜索运算符:

运算符	说明	示例
AND	两个词都必须出现(默认行为)	social AND media
OR	任意一个词出现即可	ayrshare OR socialmedia
from:	来自指定用户的推文	from:ayrshare
to:	指向指定用户的推文	to:ayrshare
#	匹配某个 hashtag	#socialmedia
@	匹配某个提及	@ayrshare
-	排除某个词	social -spam
lang:	按语言过滤	ayrshare lang:en
filter:	按内容类型过滤	ayrshare filter:links
url:	匹配某个 URL	url:ayrshare.com

cURL

curl \
  -H "Authorization: Bearer API_KEY" \
  -H "x-twitter-oauth1-api-key: YOUR_TWITTER_API_KEY" \
  -H "x-twitter-oauth1-api-secret: YOUR_TWITTER_API_SECRET" \
  -X GET "https://api.ayrshare.com/api/listen/keyword?query=ayrshare%20OR%20%23socialmedia&platform=twitter&limit=15"

200: Success

{
  "status": "success",
  "platform": "twitter",
  "query": "ayrshare OR #socialmedia",
  "tweets": [
    {
      "id": "1234567890",
      "text": "Just discovered @ayrshare for managing social media APIs!",
      "createdAt": "2026-03-22T14:30:00.000Z",
      "user": {
        "id": "987654321",
        "name": "Jane Doe",
        "screenName": "janedoe",
        "profileImageUrl": "https://pbs.twimg.com/profile_images/..."
      },
      "metrics": {
        "retweetCount": 5,
        "favoriteCount": 12
      },
      "entities": {
        "hashtags": ["socialmedia"],
        "mentions": ["ayrshare"],
        "urls": []
      },
      "inReplyToStatusId": null,
      "isRetweet": false,
      "lang": "en"
    }
  ],
  "meta": {
    "pagination": {
      "hasMore": true,
      "next": "b26v89c19zqg8o3fpds7h...",
      "limit": 15
    }
  }
}