Skip to main content
GET
/
listen
/
keyword
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"

{
  "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:
OperatorDescriptionExample
ANDBoth terms must appear (default behavior)social AND media
OREither term must appearayrshare OR socialmedia
from:Tweets from a specific userfrom:ayrshare
to:Tweets directed at a specific userto:ayrshare
#Match a hashtag#socialmedia
@Match a mention@ayrshare
-Exclude a termsocial -spam
lang:Filter by languageayrshare lang:en
filter:Filter by content typeayrshare filter:links
url:Match a URLurl:ayrshare.com
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"

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