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