> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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)](https://www.ayrshare.com/docs/dashboard/connect-social-accounts/x-twitter-byo-keys.md) for X/Twitter.

> [!WARNING]
>
> **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

**Authorization** `string` *required*

[API Key](https://www.ayrshare.com/docs/apis/overview.md#authorization) of the Primary Profile.

Format: `Authorization: Bearer API_KEY`
**Profile-Key** `string`

[Profile Key](https://www.ayrshare.com/docs/apis/overview.md#profile-key-format) of a User Profile.

Format: `Profile-Key: PROFILE_KEY`

## 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` |

```bash cURL theme={"system"}
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"
```

```javascript JavaScript theme={"system"}
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);
```

```python Python theme={"system"}
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())
```

```json 200: Success theme={"system"}
{
  "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
    }
  }
}
```

```json 400: Missing Query theme={"system"}
{
  "action": "listen",
  "status": "error",
  "code": 428,
  "message": "Missing required `query` parameter for keyword search"
}
```

```json 400: Unsupported Platform theme={"system"}
{
  "action": "listen",
  "status": "error",
  "code": 429,
  "message": "Missing or unsupported `platform` parameter. Currently only `twitter` is supported"
}
```

```json 403: Plan Required theme={"system"}
{
  "action": "listen",
  "status": "error",
  "code": 430,
  "message": "Keyword search requires Premium, Launch, Business, or Enterprise tier"
}
```

```json 403: BYOK Keys Required theme={"system"}
{
  "action": "listen",
  "status": "error",
  "code": 431,
  "message": "Keyword search requires BYOK (Bring Your Own Keys) for X/Twitter"
}
```

```json 429: Daily Limit Reached theme={"system"}
{
  "action": "listen",
  "status": "error",
  "code": 432,
  "message": "Daily keyword search limit exceeded. Limit resets at midnight UTC"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.