Felo APIs

X Search API

Cerca utenti X, tweet, timeline e risposte con metadati di paginazione.

POST/v2/x/tweet/search

Autenticazione

Bearer API key

Tipo di contenuto

application/json

Note sui limiti

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

Chat API

La X Search API dà accesso ai dati di X (Twitter), compresi profili utente, ricerca dei tweet, tweet di un utente e risposte ai tweet.

Autenticazione

Tutte le richieste richiedono una chiave API nell'header Authorization:

Authorization: Bearer YOUR_API_KEY

Uso con agenti IA

Installa il pacchetto completo felo-ai per dare a un agente X Search e ogni altra Felo Skill disponibile. L'installer individua dinamicamente ogni directory del pacchetto che contiene SKILL.md, invece di mantenere un elenco fisso di Skill. Installa tutte le Skill trovate in Codex ~/.codex/skills, Claude Code ~/.claude/skills, OpenClaw ~/.agents/skills o Hermes Agent ~/.hermes/skills. Vedi la guida alla configurazione manuale degli agenti IA per le istruzioni di installazione, chiave API e verifica su ogni piattaforma.

1. Ottenere le informazioni di un utente

Recupera in blocco i profili degli utenti X per nome utente.

Endpoint

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

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`usernames`	array di stringhe	Sì	Elenco dei nomi utente X da cercare

Esempio

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"]
  }'

Risposta di successo (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"
      }
    ]
  }
}

Campi dell'oggetto utente

Campo	Tipo	Descrizione
`user_id`	string	ID utente X
`username`	string	Handle X (senza @)
`display_name`	string	Nome visualizzato
`description`	string	Biografia dell'utente
`followers_count`	integer	Numero di follower
`following_count`	integer	Numero di account seguiti
`tweet_count`	integer	Tweet totali
`verified`	boolean	Se l'account è verificato
`blue_verified`	boolean	Se l'account ha la verifica Blue
`verified_type`	string	Tipo di verifica
`profile_image_url`	string	URL dell'immagine del profilo
`cover_image_url`	string	URL dell'immagine di copertina
`created_at`	string	Data di creazione dell'account
`location`	string	Località dell'utente
`url`	string	URL del sito web dell'utente
`protected`	boolean	Se l'account è protetto
`favorites_count`	integer	Numero di like
`media_count`	integer	Numero di post multimediali
`can_dm`	boolean	Se i messaggi diretti sono aperti
`is_automated`	boolean	Se l'account è automatizzato
`pinned_tweet_ids`	array di stringhe	ID dei tweet fissati

2. Cercare utenti

Cerca utenti X per parola chiave.

Endpoint

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

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`query`	string	Sì	Parola chiave di ricerca
`cursor`	string	No	Cursore di paginazione dalla risposta precedente

Esempio

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

Risposta di successo (200)

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

Campi della risposta

Campo	Tipo	Descrizione
`total`	integer	Numero totale di risultati
`has_next`	boolean	Se sono disponibili altri risultati
`next_cursor`	string	Cursore per la pagina successiva
`users`	array	Elenco di oggetti utente (vedi sezione 1)

3. Ottenere i tweet di un utente

Recupera i tweet di un utente X specifico.

Endpoint

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

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`x_user_id`	string	No	ID utente X (fornisci `x_user_id` o `username`)
`username`	string	No	Nome utente X (fornisci `x_user_id` o `username`)
`limit`	integer	No	Numero di tweet da restituire
`cursor`	string	No	Cursore di paginazione
`include_replies`	boolean	No	Se includere le risposte

Esempio

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

Risposta di successo (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"
      }
    ]
  }
}

Campi dell'oggetto tweet

Campo	Tipo	Descrizione
`id`	string	ID del tweet
`content`	string	Contenuto testuale del tweet
`author`	object	Oggetto utente dell'autore (vedi sezione 1)
`created_at`	string	Ora di creazione del tweet
`metrics`	object	Metriche di coinvolgimento (vedi sotto)
`replies`	array	Tweet di risposta (se disponibili)
`conversation_id`	string	ID del thread della conversazione
`media_urls`	array	Contenuti multimediali allegati
`hashtags`	array di stringhe	Hashtag nel tweet
`mentions`	array di stringhe	Nomi utente menzionati
`urls`	array di stringhe	URL nel tweet
`url`	string	Permalink al tweet
`source`	string	Fonte del tweet (ad es. "Twitter Web App")
`lang`	string	Codice lingua del tweet
`is_reply`	boolean	Se si tratta di una risposta
`in_reply_to_id`	string	ID del tweet a cui si risponde
`in_reply_to_user_id`	string	ID utente del tweet a cui si risponde
`in_reply_to_username`	string	Nome utente del tweet a cui si risponde
`quoted_tweet`	object	Oggetto del tweet citato (ricorsivo)
`retweeted_tweet`	object	Oggetto del tweet ripubblicato (ricorsivo)
`is_limited_reply`	boolean	Se le risposte sono limitate

Campi dell'oggetto metrics

Campo	Tipo	Descrizione
`retweet_count`	integer	Numero di retweet
`favorite_count`	integer	Numero di like
`reply_count`	integer	Numero di risposte
`quote_count`	integer	Numero di citazioni
`view_count`	integer	Numero di visualizzazioni
`bookmark_count`	integer	Numero di segnalibri

4. Cercare tweet

Cerca tweet di X per parola chiave con supporto per query avanzate.

Endpoint

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

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`query`	string	Sì	Query di ricerca (supporta la sintassi di ricerca avanzata)
`query_type`	string	No	Filtro per tipo di query
`since_time`	integer	No	Filtro sull'ora di inizio (timestamp Unix in secondi)
`until_time`	integer	No	Filtro sull'ora di fine (timestamp Unix in secondi)
`limit`	integer	No	Numero di tweet da restituire
`cursor`	string	No	Cursore di paginazione

Esempio

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

Risposta di successo (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 }
      }
    ]
  }
}

Campi della risposta

Campo	Tipo	Descrizione
`total`	integer	Numero totale di risultati
`has_next`	boolean	Se sono disponibili altri risultati
`next_cursor`	string	Cursore per la pagina successiva
`tweets`	array	Elenco di oggetti tweet (vedi sezione 3)

5. Ottenere le risposte a un tweet

Recupera le risposte a tweet specifici.

Endpoint

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

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
`tweet_ids`	array di stringhe	Sì	ID dei tweet di cui ottenere le risposte
`cursor`	string	No	Cursore di paginazione
`since_time`	integer	No	Filtro sull'ora di inizio (timestamp Unix)
`until_time`	integer	No	Filtro sull'ora di fine (timestamp Unix)

Esempio

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"]
  }'

Risposta di successo (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"
          }
        ]
      }
    ]
  }
}

Campi della risposta

Campo	Tipo	Descrizione
`results`	array	Elenco di oggetti risultato delle risposte
`results[].tweet_id`	string	ID del tweet originale
`results[].total`	integer	Numero totale di risposte
`results[].has_next`	boolean	Se sono disponibili altre risposte
`results[].next_cursor`	string	Cursore per la pagina successiva
`results[].replies`	array	Elenco di oggetti tweet di risposta (vedi sezione 3)

Codici di errore

Codice	Stato HTTP	Descrizione
`UNAUTHORIZED`	401	La chiave API non è valida o è revocata
`X_SEARCH_FAILED`	400/500	Richiesta di ricerca X non riuscita (controlla i parametri o l'errore downstream)
`RATE_LIMIT_EXCEEDED`	429	Troppe richieste, riprova dopo un breve ritardo
`insufficient_credits`	402	Crediti insufficienti per completare la richiesta

Crediti e rate limit

Costo in crediti

Ogni chiamata API deduce crediti in base al numero di risultati restituiti:

Endpoint	Costo in crediti
`POST /x/user/info`	1 credito per utente restituito
`POST /x/user/search`	1 credito per utente restituito
`POST /x/user/tweets`	1 credito per tweet restituito
`POST /x/tweet/search`	1 credito per tweet restituito
`POST /x/tweet/replies`	1 credito per risposta restituita

I crediti vengono dedotti al termine della richiesta, in base al numero effettivo di risultati. Se una richiesta restituisce 0 risultati, non vengono dedotti crediti.

Saldo minimo richiesto: il tuo account deve avere almeno 10 crediti per effettuare qualsiasi richiesta all'API X. Le richieste con meno di 10 crediti vengono rifiutate con HTTP 402.

Rate limit

I rate limit sono applicati in base al servizio API e alle politiche dell'account correnti. In caso di rate limit, l'API restituisce HTTP 429. L'header Retry-After indica il tempo di attesa consigliato in secondi. Usa la documentazione del servizio più recente e le risposte API effettive per gestire i rate limit; non è richiesto un abbonamento per usare la piattaforma.