Pesquisar tweets por palavra-chave

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
    }
  }
}

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

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
    }
  }
}

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

Pesquise no X/Twitter tweets que correspondam a palavras-chave, hashtags e operadores de pesquisa avançada. Retorna dados normalizados dos tweets, incluindo informações do usuário, métricas de engajamento e entidades. Este endpoint exige Bring Your Own Keys (BYOK) para o X/Twitter.

Limitações importantes

Somente tweets dos últimos ~7 dias estão disponíveis (limitação da API do X).
Limite diário padrão de 25 chamadas.
Chaves BYOK para X/Twitter são obrigatórias.

Parâmetros do header

Parâmetros de query

string

obrigatório

Consulta de pesquisa por palavra-chave. Suporta operadores de pesquisa do X/Twitter (veja a tabela abaixo).Exemplos: ayrshare, #socialmedia, ayrshare OR #socialmedia, from:ayrshare.

string

obrigatório

Deve ser twitter.

integer

padrão:15

Número máximo de tweets a retornar. Deve estar entre 10 e 100.

string

Retorna tweets com um ID maior (mais novos) que este valor. Útil para buscar apenas novos tweets desde uma requisição anterior.

string

Retorna tweets com um ID menor (mais antigos) que este valor. Útil para paginar retroativamente pelos resultados.

string

Token de paginação do meta.pagination.next de uma resposta anterior. Use-o para buscar a próxima página de resultados.

Operadores de pesquisa

O parâmetro query suporta os seguintes operadores de pesquisa do X/Twitter:

Operador	Descrição	Exemplo
`AND`	Ambos os termos devem aparecer (comportamento padrão)	`social AND media`
`OR`	Qualquer um dos termos deve aparecer	`ayrshare OR socialmedia`
`from:`	Tweets de um usuário específico	`from:ayrshare`
`to:`	Tweets direcionados a um usuário específico	`to:ayrshare`
`#`	Corresponder a uma hashtag	`#socialmedia`
`@`	Corresponder a uma menção	`@ayrshare`
`-`	Excluir um termo	`social -spam`
`lang:`	Filtrar por idioma	`ayrshare lang:en`
`filter:`	Filtrar por tipo de conteúdo	`ayrshare filter:links`
`url:`	Corresponder a uma 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
    }
  }
}

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

⌘I

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Parâmetros do header

Parâmetros de query

Operadores de pesquisa

​Parâmetros do header

​Parâmetros de query

​Operadores de pesquisa

Parâmetros do header

Parâmetros de query

Operadores de pesquisa