Felo APIs

X Search API

Pesquise usuários do X, tweets, timelines e respostas com metadados de paginação.

POST/v2/x/tweet/search

Autenticação

Bearer API key

Tipo de conteúdo

application/json

Notas de limite

1 request per 10 seconds, 3 per minute, 10 per 10 minutes.

Chat API

A X Search API oferece acesso a dados do X (Twitter), incluindo perfis de usuários, busca de tweets, tweets de usuários e respostas a tweets.

Autenticação

Todas as requisições exigem uma chave de API no cabeçalho Authorization:

Authorization: Bearer YOUR_API_KEY

Uso com agentes de IA

Instale o pacote completo felo-ai para dar a um agente a X Search e todos os demais Felo Skills disponíveis. O instalador descobre dinamicamente todos os diretórios de pacote que contêm SKILL.md, em vez de manter uma lista fixa de Skills. Instale todos os Skills descobertos em ~/.codex/skills para o Codex, ~/.claude/skills para o Claude Code, ~/.agents/skills para o OpenClaw ou ~/.hermes/skills para o Hermes Agent. Consulte o guia de configuração manual de agentes de IA para ver as instruções de instalação, de chave de API e de verificação de cada plataforma.

1. Obter informações de usuário

Recupere perfis de usuários do X em lote por nome de usuário.

Endpoint

POST https://openapi.felo.ai/v2/x/user/info

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`usernames`	array de strings	Sim	Lista de nomes de usuário do X a consultar

Exemplo

curl -X POST 'https://openapi.felo.ai/v2/x/user/info' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "usernames": ["elonmusk", "OpenAI"]
  }'

Resposta de sucesso (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 2,
    "users": [
      {
        "user_id": "44196397",
        "username": "elonmusk",
        "display_name": "Elon Musk",
        "description": "...",
        "followers_count": 100000000,
        "following_count": 500,
        "tweet_count": 30000,
        "verified": true,
        "blue_verified": true,
        "profile_image_url": "https://pbs.twimg.com/...",
        "created_at": "2009-06-02T00:00:00Z",
        "location": "Mars"
      }
    ]
  }
}

Campos do objeto de usuário

Campo	Tipo	Descrição
`user_id`	string	ID do usuário no X
`username`	string	Nome de usuário no X (sem @)
`display_name`	string	Nome de exibição
`description`	string	Bio do usuário
`followers_count`	integer	Número de seguidores
`following_count`	integer	Número de contas seguidas
`tweet_count`	integer	Total de tweets
`verified`	boolean	Se a conta é verificada
`blue_verified`	boolean	Se a conta tem verificação Blue
`verified_type`	string	Tipo de verificação
`profile_image_url`	string	URL da imagem de perfil
`cover_image_url`	string	URL da imagem de capa
`created_at`	string	Data de criação da conta
`location`	string	Localização do usuário
`url`	string	URL do site do usuário
`protected`	boolean	Se a conta é protegida
`favorites_count`	integer	Número de curtidas
`media_count`	integer	Número de publicações com mídia
`can_dm`	boolean	Se a DM está aberta
`is_automated`	boolean	Se a conta é automatizada
`pinned_tweet_ids`	array de strings	IDs dos tweets fixados

2. Buscar usuários

Busque usuários do X por palavra-chave.

Endpoint

POST https://openapi.felo.ai/v2/x/user/search

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`query`	string	Sim	Palavra-chave de busca
`cursor`	string	Não	Cursor de paginação da resposta anterior

Exemplo

curl -X POST 'https://openapi.felo.ai/v2/x/user/search' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "artificial intelligence"
  }'

Resposta de sucesso (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 50,
    "has_next": true,
    "next_cursor": "cursor_abc123",
    "users": [
      {
        "user_id": "...",
        "username": "...",
        "display_name": "..."
      }
    ]
  }
}

Campos da resposta

Campo	Tipo	Descrição
`total`	integer	Número total de resultados
`has_next`	boolean	Se há mais resultados disponíveis
`next_cursor`	string	Cursor para a próxima página
`users`	array	Lista de objetos de usuário (veja a seção 1)

3. Obter tweets de um usuário

Recupere tweets de um usuário específico do X.

Endpoint

POST https://openapi.felo.ai/v2/x/user/tweets

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`x_user_id`	string	Não	ID do usuário no X (informe `x_user_id` ou `username`)
`username`	string	Não	Nome de usuário no X (informe `x_user_id` ou `username`)
`limit`	integer	Não	Número de tweets a retornar
`cursor`	string	Não	Cursor de paginação
`include_replies`	boolean	Não	Se deve incluir respostas

Exemplo

curl -X POST 'https://openapi.felo.ai/v2/x/user/tweets' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "elonmusk",
    "limit": 20
  }'

Resposta de sucesso (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 20,
    "has_next": true,
    "next_cursor": "cursor_def456",
    "tweets": [
      {
        "id": "1234567890",
        "content": "Tweet content here...",
        "author": { "user_id": "...", "username": "elonmusk" },
        "created_at": "2026-03-09T12:00:00Z",
        "metrics": {
          "retweet_count": 1000,
          "favorite_count": 5000,
          "reply_count": 200,
          "quote_count": 100,
          "view_count": 500000,
          "bookmark_count": 50
        },
        "hashtags": ["AI"],
        "mentions": ["OpenAI"],
        "url": "https://x.com/elonmusk/status/1234567890",
        "lang": "en"
      }
    ]
  }
}

Campos do objeto de tweet

Campo	Tipo	Descrição
`id`	string	ID do tweet
`content`	string	Conteúdo de texto do tweet
`author`	object	Objeto de usuário do autor (veja a seção 1)
`created_at`	string	Data de criação do tweet
`metrics`	object	Métricas de engajamento (veja abaixo)
`replies`	array	Tweets de resposta (se disponíveis)
`conversation_id`	string	ID da thread da conversa
`media_urls`	array	Mídia anexada
`hashtags`	array de strings	Hashtags no tweet
`mentions`	array de strings	Nomes de usuário mencionados
`urls`	array de strings	URLs no tweet
`url`	string	Link permanente para o tweet
`source`	string	Origem do tweet (por exemplo, "Twitter Web App")
`lang`	string	Código de idioma do tweet
`is_reply`	boolean	Se este tweet é uma resposta
`in_reply_to_id`	string	ID do tweet que está sendo respondido
`in_reply_to_user_id`	string	ID do usuário do tweet que está sendo respondido
`in_reply_to_username`	string	Nome de usuário do tweet que está sendo respondido
`quoted_tweet`	object	Objeto do tweet citado (recursivo)
`retweeted_tweet`	object	Objeto do tweet retuitado (recursivo)
`is_limited_reply`	boolean	Se as respostas estão limitadas

Campos do objeto de métricas

Campo	Tipo	Descrição
`retweet_count`	integer	Número de retuítes
`favorite_count`	integer	Número de curtidas
`reply_count`	integer	Número de respostas
`quote_count`	integer	Número de citações
`view_count`	integer	Número de visualizações
`bookmark_count`	integer	Número de favoritos salvos

4. Buscar tweets

Busque tweets do X por palavra-chave com suporte a consultas avançadas.

Endpoint

POST https://openapi.felo.ai/v2/x/tweet/search

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`query`	string	Sim	Consulta de busca (aceita sintaxe de busca avançada)
`query_type`	string	Não	Filtro de tipo de consulta
`since_time`	integer	Não	Filtro de horário inicial (timestamp Unix em segundos)
`until_time`	integer	Não	Filtro de horário final (timestamp Unix em segundos)
`limit`	integer	Não	Número de tweets a retornar
`cursor`	string	Não	Cursor de paginação

Exemplo

curl -X POST 'https://openapi.felo.ai/v2/x/tweet/search' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "artificial intelligence",
    "limit": 20
  }'

Resposta de sucesso (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "total": 20,
    "has_next": true,
    "next_cursor": "cursor_ghi789",
    "tweets": [
      {
        "id": "...",
        "content": "...",
        "author": { "user_id": "...", "username": "..." },
        "created_at": "2026-03-09T12:00:00Z",
        "metrics": { "retweet_count": 100, "favorite_count": 500 }
      }
    ]
  }
}

Campos da resposta

Campo	Tipo	Descrição
`total`	integer	Número total de resultados
`has_next`	boolean	Se há mais resultados disponíveis
`next_cursor`	string	Cursor para a próxima página
`tweets`	array	Lista de objetos de tweet (veja a seção 3)

5. Obter respostas a tweets

Recupere respostas para tweets específicos.

Endpoint

POST https://openapi.felo.ai/v2/x/tweet/replies

Corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`tweet_ids`	array de strings	Sim	ID(s) de tweet para os quais obter respostas
`cursor`	string	Não	Cursor de paginação
`since_time`	integer	Não	Filtro de horário inicial (timestamp Unix)
`until_time`	integer	Não	Filtro de horário final (timestamp Unix)

Exemplo

curl -X POST 'https://openapi.felo.ai/v2/x/tweet/replies' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "tweet_ids": ["1234567890"]
  }'

Resposta de sucesso (200)

{
  "status": "ok",
  "message": null,
  "data": {
    "results": [
      {
        "tweet_id": "1234567890",
        "total": 10,
        "has_next": true,
        "next_cursor": "cursor_jkl012",
        "replies": [
          {
            "id": "...",
            "content": "Great tweet!",
            "author": { "user_id": "...", "username": "..." },
            "created_at": "2026-03-09T12:30:00Z"
          }
        ]
      }
    ]
  }
}

Campos da resposta

Campo	Tipo	Descrição
`results`	array	Lista de objetos de resultado de respostas
`results[].tweet_id`	string	ID do tweet original
`results[].total`	integer	Número total de respostas
`results[].has_next`	boolean	Se há mais respostas disponíveis
`results[].next_cursor`	string	Cursor para a próxima página
`results[].replies`	array	Lista de objetos de tweet de resposta (veja a seção 3)

Códigos de erro

Código	Status HTTP	Descrição
`UNAUTHORIZED`	401	A chave de API é inválida ou foi revogada
`X_SEARCH_FAILED`	400/500	A requisição de busca no X falhou (verifique os parâmetros ou o erro downstream)
`RATE_LIMIT_EXCEEDED`	429	Requisições demais; tente novamente após um curto intervalo
`insufficient_credits`	402	Créditos de serviço insuficientes para concluir a requisição

Créditos e limites de requisições

Custos em créditos

Cada chamada à API desconta créditos com base no número de resultados retornados:

Endpoint	Custo em créditos
`POST /x/user/info`	1 crédito por usuário retornado
`POST /x/user/search`	1 crédito por usuário retornado
`POST /x/user/tweets`	1 crédito por tweet retornado
`POST /x/tweet/search`	1 crédito por tweet retornado
`POST /x/tweet/replies`	1 crédito por resposta retornada

Os créditos são descontados após a conclusão da requisição, com base no número real de resultados. Se uma requisição retornar 0 resultados, nenhum crédito é descontado.

Saldo mínimo exigido: sua conta precisa ter pelo menos 10 créditos de serviço para fazer qualquer requisição à API do X. Requisições feitas com menos de 10 créditos serão rejeitadas com HTTP 402.

Limites de requisições

Os limites de requisições são aplicados conforme os serviços de API e as políticas de conta vigentes. Quando o limite é atingido, a API retorna HTTP 429. O cabeçalho Retry-After indica o tempo de espera sugerido em segundos. Use a documentação atualizada do serviço e as respostas reais da API para lidar com os limites; não é preciso assinatura para usar a plataforma.