Buscar tweets por palabra clave

Busca en X/Twitter tweets que coincidan con palabras clave o 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."
}

Busca en X/Twitter tweets que coincidan con palabras clave, hashtags y operadores de búsqueda avanzada. Devuelve datos de tweets normalizados, incluyendo información del usuario, métricas de interacción y entidades.

Este endpoint requiere Bring Your Own Keys (BYOK) para X/Twitter.

Limitaciones importantes

• Solo están disponibles los tweets de los últimos ~7 días (limitación de la API de X).
• Límite diario predeterminado de 25 llamadas.
• Se requieren las claves BYOK para X/Twitter.

​

Parámetros del header

​

Parámetros de query

query · string · requerido

Consulta de búsqueda por palabra clave. Admite operadores de búsqueda de X/Twitter (consulta la tabla a continuación).

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

platform · string · requerido

Debe ser twitter.

limit · integer · predeterminado: 15

Número máximo de tweets a devolver. Debe estar entre 10 y 100.

sinceId · string

Devuelve tweets con un ID mayor (más reciente) que este valor. Útil para recuperar solo los tweets nuevos desde una solicitud anterior.

untilId · string

Devuelve tweets con un ID menor (más antiguo) que este valor. Útil para paginar hacia atrás a través de los resultados.

next · string

Token de paginación de un meta.pagination.next de una respuesta anterior. Úsalo para obtener la siguiente página de resultados.

​

Operadores de búsqueda

El parámetro query admite los siguientes operadores de búsqueda de X/Twitter:

Operador	Descripción	Ejemplo
AND	Ambos términos deben aparecer (comportamiento por defecto)	social AND media
OR	Cualquiera de los términos debe aparecer	ayrshare OR socialmedia
from:	Tweets de un usuario específico	from:ayrshare
to:	Tweets dirigidos a un usuario específico	to:ayrshare
#	Coincide con un hashtag	#socialmedia
@	Coincide con una mención	@ayrshare
-	Excluye un término	social -spam
lang:	Filtra por idioma	ayrshare lang:en
filter:	Filtra por tipo de contenido	ayrshare filter:links
url:	Coincide con una 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."
}