البحث عن التغريدات حسب الكلمة المفتاحية

ابحث في X/Twitter عن التغريدات التي تطابق الكلمات المفتاحية أو الوسوم

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: نجاح

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

ابحث في X/Twitter عن التغريدات التي تطابق الكلمات المفتاحية والوسوم وعوامل البحث المتقدمة. تُعيد بيانات التغريدات المُطبَّعة بما في ذلك معلومات المستخدم ومقاييس التفاعل والكيانات.

تتطلب نقطة النهاية هذه أحضر مفاتيحك الخاصة (BYOK) لـ X/Twitter.

قيود مهمة

• التغريدات من الأيام السبعة الماضية فقط متاحة (قيد X API).
• الحد الأقصى الافتراضي هو 25 استدعاءً يوميًا.
• مطلوب مفاتيح BYOK لـ X/Twitter.

​

معلمات الترويسة

​

معلمات الاستعلام

query · string · مطلوب

استعلام البحث بكلمة مفتاحية. يدعم عوامل البحث في X/Twitter (انظر الجدول أدناه).

أمثلة: ayrshare، #socialmedia، ayrshare OR #socialmedia، from:ayrshare.

platform · string · مطلوب

يجب أن يكون twitter.

limit · integer · افتراضي: 15

الحد الأقصى لعدد التغريدات المراد إعادتها. يجب أن يكون بين 10 و100.

sinceId · string

تُعيد التغريدات التي يكون معرّفها أكبر من (أحدث من) هذه القيمة. مفيدة لجلب التغريدات الجديدة فقط منذ الطلب السابق.

untilId · string

تُعيد التغريدات التي يكون معرّفها أصغر من (أقدم من) هذه القيمة. مفيدة للتصفح للخلف عبر النتائج.

next · string

رمز الترقيم من meta.pagination.next في الاستجابة السابقة. استخدمه لجلب الصفحة التالية من النتائج.

​

عوامل البحث

تدعم معلمة query عوامل البحث التالية في X/Twitter:

العامل	الوصف	المثال
AND	يجب أن يظهر كلا المصطلحين (السلوك الافتراضي)	social AND media
OR	يجب أن يظهر أحد المصطلحين	ayrshare OR socialmedia
from:	التغريدات من مستخدم محدد	from:ayrshare
to:	التغريدات الموجهة إلى مستخدم محدد	to:ayrshare
#	مطابقة وسم	#socialmedia
@	مطابقة إشارة	@ayrshare
-	استبعاد مصطلح	social -spam
lang:	فلترة حسب اللغة	ayrshare lang:en
filter:	فلترة حسب نوع المحتوى	ayrshare filter:links
url:	مطابقة عنوان 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: نجاح

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