Search Tweets by Keyword

Search X/Twitter for tweets matching keywords or hashtags

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"

const API_KEY = "API_KEY";

fetch(
  "https://api.ayrshare.com/api/listen/keyword?query=ayrshare%20OR%20%23socialmedia&platform=twitter&limit=15",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "x-twitter-oauth1-api-key": "YOUR_TWITTER_API_KEY",
      "x-twitter-oauth1-api-secret": "YOUR_TWITTER_API_SECRET"
    }
  }
)
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch(console.error);

import requests

headers = {
    'Authorization': 'Bearer API_KEY',
    'x-twitter-oauth1-api-key': 'YOUR_TWITTER_API_KEY',
    'x-twitter-oauth1-api-secret': 'YOUR_TWITTER_API_SECRET'
}

params = {
    'query': 'ayrshare OR #socialmedia',
    'platform': 'twitter',
    'limit': 15
}

r = requests.get('https://api.ayrshare.com/api/listen/keyword', headers=headers, params=params)

print(r.json())

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

{
  "status": "error",
  "code": 101,
  "message": "Missing or incorrect parameters. Please verify with the docs.",
  "details": "The 'query' parameter is required."
}

{
  "status": "error",
  "code": 401,
  "message": "Unauthorized. BYOK keys for X/Twitter are required.",
  "details": "Please set up your X/Twitter API keys. See https://docs.ayrshare.com/dashboard/connect-social-accounts/x-twitter-byo-keys"
}

{
  "status": "error",
  "code": 429,
  "message": "Rate limit exceeded. Daily limit of 25 keyword search calls reached.",
  "details": "Please try again tomorrow or contact support for higher limits."
}

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"

const API_KEY = "API_KEY";

fetch(
  "https://api.ayrshare.com/api/listen/keyword?query=ayrshare%20OR%20%23socialmedia&platform=twitter&limit=15",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "x-twitter-oauth1-api-key": "YOUR_TWITTER_API_KEY",
      "x-twitter-oauth1-api-secret": "YOUR_TWITTER_API_SECRET"
    }
  }
)
  .then((res) => res.json())
  .then((json) => console.log(json))
  .catch(console.error);

import requests

headers = {
    'Authorization': 'Bearer API_KEY',
    'x-twitter-oauth1-api-key': 'YOUR_TWITTER_API_KEY',
    'x-twitter-oauth1-api-secret': 'YOUR_TWITTER_API_SECRET'
}

params = {
    'query': 'ayrshare OR #socialmedia',
    'platform': 'twitter',
    'limit': 15
}

r = requests.get('https://api.ayrshare.com/api/listen/keyword', headers=headers, params=params)

print(r.json())

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

{
  "status": "error",
  "code": 101,
  "message": "Missing or incorrect parameters. Please verify with the docs.",
  "details": "The 'query' parameter is required."
}

{
  "status": "error",
  "code": 401,
  "message": "Unauthorized. BYOK keys for X/Twitter are required.",
  "details": "Please set up your X/Twitter API keys. See https://docs.ayrshare.com/dashboard/connect-social-accounts/x-twitter-byo-keys"
}

{
  "status": "error",
  "code": 429,
  "message": "Rate limit exceeded. Daily limit of 25 keyword search calls reached.",
  "details": "Please try again tomorrow or contact support for higher limits."
}