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())
{
"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
}
}
}
{
"action": "listen",
"status": "error",
"code": 428,
"message": "Missing required `query` parameter for keyword search"
}
{
"action": "listen",
"status": "error",
"code": 429,
"message": "Missing or unsupported `platform` parameter. Currently only `twitter` is supported"
}
{
"action": "listen",
"status": "error",
"code": 430,
"message": "Keyword search requires Premium, Launch, Business, or Enterprise tier"
}
{
"action": "listen",
"status": "error",
"code": 431,
"message": "Keyword search requires BYOK (Bring Your Own Keys) for X/Twitter"
}
{
"action": "listen",
"status": "error",
"code": 432,
"message": "Daily keyword search limit exceeded. Limit resets at midnight UTC"
}
Keyword
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 \
-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())
{
"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
}
}
}
{
"action": "listen",
"status": "error",
"code": 428,
"message": "Missing required `query` parameter for keyword search"
}
{
"action": "listen",
"status": "error",
"code": 429,
"message": "Missing or unsupported `platform` parameter. Currently only `twitter` is supported"
}
{
"action": "listen",
"status": "error",
"code": 430,
"message": "Keyword search requires Premium, Launch, Business, or Enterprise tier"
}
{
"action": "listen",
"status": "error",
"code": 431,
"message": "Keyword search requires BYOK (Bring Your Own Keys) for X/Twitter"
}
{
"action": "listen",
"status": "error",
"code": 432,
"message": "Daily keyword search limit exceeded. Limit resets at midnight UTC"
}
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
Keyword search query. Supports X/Twitter search operators (see table below).Examples:
ayrshare, #socialmedia, ayrshare OR #socialmedia, from:ayrshare.Returns tweets with an ID greater than (newer than) this value. Useful for fetching only new tweets since a previous request.
Returns tweets with an ID less than (older than) this value. Useful for paginating backwards through results.
Pagination token from a previous response’s
meta.pagination.next. Use this to fetch the next page of results.Search Operators
Thequery 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 \
-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())
{
"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
}
}
}
{
"action": "listen",
"status": "error",
"code": 428,
"message": "Missing required `query` parameter for keyword search"
}
{
"action": "listen",
"status": "error",
"code": 429,
"message": "Missing or unsupported `platform` parameter. Currently only `twitter` is supported"
}
{
"action": "listen",
"status": "error",
"code": 430,
"message": "Keyword search requires Premium, Launch, Business, or Enterprise tier"
}
{
"action": "listen",
"status": "error",
"code": 431,
"message": "Keyword search requires BYOK (Bring Your Own Keys) for X/Twitter"
}
{
"action": "listen",
"status": "error",
"code": 432,
"message": "Daily keyword search limit exceeded. Limit resets at midnight UTC"
}