Rechercher des tweets par mot-clé

Rechercher sur X/Twitter les tweets correspondant à des mots-clés ou 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."
}

Recherchez sur X/Twitter les tweets correspondant à des mots-clés, des hashtags et des opérateurs de recherche avancée. Renvoie des données de tweets normalisées incluant les informations utilisateur, les métriques d’engagement et les entités.

Ce point de terminaison requiert Bring Your Own Keys (BYOK) pour X/Twitter.

Limitations importantes

• Seuls les tweets des ~7 derniers jours sont disponibles (limitation de l’API X).
• Limite quotidienne par défaut de 25 appels.
• Les clés BYOK pour X/Twitter sont requises.

​

Paramètres d’en-tête

​

Paramètres de requête

query · string · requis

Requête de recherche par mot-clé. Prend en charge les opérateurs de recherche X/Twitter (voir tableau ci-dessous).

Exemples : ayrshare, #socialmedia, ayrshare OR #socialmedia, from:ayrshare.

platform · string · requis

Doit être twitter.

limit · integer · défaut: 15

Nombre maximum de tweets à retourner. Doit être compris entre 10 et 100.

sinceId · string

Retourne les tweets dont l’ID est supérieur à (plus récent que) cette valeur. Utile pour récupérer uniquement les nouveaux tweets depuis une requête précédente.

untilId · string

Retourne les tweets dont l’ID est inférieur à (plus ancien que) cette valeur. Utile pour paginer à rebours dans les résultats.

next · string

Jeton de pagination provenant du champ meta.pagination.next d’une réponse précédente. Utilisez-le pour récupérer la page de résultats suivante.

​

Opérateurs de recherche

Le paramètre query prend en charge les opérateurs de recherche X/Twitter suivants :

Opérateur	Description	Exemple
AND	Les deux termes doivent apparaître (comportement par défaut)	social AND media
OR	L’un ou l’autre des termes doit apparaître	ayrshare OR socialmedia
from:	Tweets d’un utilisateur spécifique	from:ayrshare
to:	Tweets adressés à un utilisateur spécifique	to:ayrshare
#	Correspondre à un hashtag	#socialmedia
@	Correspondre à une mention	@ayrshare
-	Exclure un terme	social -spam
lang:	Filtrer par langue	ayrshare lang:en
filter:	Filtrer par type de contenu	ayrshare filter:links
url:	Correspondre à une 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."
}