Search Tweets by Keyword

Search X/Twitter for tweets matching keywords, hashtags, and search operators, returning user info and engagement metrics. Requires BYOK for X/Twitter.

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
    }
  }
}

Search X/Twitter for tweets matching keywords, hashtags, and advanced search operators. Returns normalized tweet data including user info, engagement metrics, and entities.

This endpoint requires Bring Your Own Keys (BYOK) for X/Twitter.

Important Limitations

• Only tweets from the last ~7 days are available (X API limitation).
• Default daily limit of 25 calls.
• BYOK keys for X/Twitter are required.

​

Header Parameters

​

Query Parameters

query · string · required

Keyword search query. Supports X/Twitter search operators (see table below).

Examples: ayrshare, #socialmedia, ayrshare OR #socialmedia, from:ayrshare.

platform · string · required

Must be twitter.

limit · integer · default: 15

Maximum number of tweets to return. Must be between 10 and 100.

sinceId · string

Returns tweets with an ID greater than (newer than) this value. Useful for fetching only new tweets since a previous request.

untilId · string

Returns tweets with an ID less than (older than) this value. Useful for paginating backwards through results.

next · string

Pagination token from a previous response’s meta.pagination.next. Use this to fetch the next page of results.

​

Search Operators

The query parameter supports the following X/Twitter search operators:

Operator	Description	Example
AND	Both terms must appear (default behavior)	social AND media
OR	Either term must appear	ayrshare OR socialmedia
from:	Tweets from a specific user	from:ayrshare
to:	Tweets directed at a specific user	to:ayrshare
#	Match a hashtag	#socialmedia
@	Match a mention	@ayrshare
-	Exclude a term	social -spam
lang:	Filter by language	ayrshare lang:en
filter:	Filter by content type	ayrshare filter:links
url:	Match a 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
    }
  }
}