Filtrare per handle X
In questa pagina
Mira ad account specifici su X
Proprio come la Ricerca Web ti permette di filtrare per dominio, la Ricerca X ti consente di filtrare per account (handle). Puoi limitare le ricerche ai post pubblicati da un insieme specifico di account oppure escludere determinati account dai risultati. Questo filtraggio è essenziale per casi d’uso come il monitoraggio, il tracciamento del brand o l’analisi degli influencer.
I due parametri di filtraggio
La Ricerca X offre due parametri per filtrare gli handle:
allowed_x_handles: limita la ricerca ai post degli account elencati (allowlist)excluded_x_handles: esclude i post degli account elencati (blocklist)
Come per la Ricerca Web, questi parametri sono mutuamente esclusivi. Non puoi utilizzarli entrambi nella stessa richiesta.
Ciascun parametro accetta un array di massimo 10 handle (rispetto ai 5 domini della Ricerca Web).
Utilizzo di allowed_x_handles (allowlist)
Questo parametro è ideale per monitorare le comunicazioni di account specifici:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What are the latest announcements from xAI?",
tools=[{
"type": "x_search",
"allowed_x_handles": ["xaboratory", "xaboratorydev"]
}]
)
Il modello cercherà esclusivamente i post pubblicati da questi account.
Casi d’uso dell’allowlist
- Intelligence competitiva: monitora gli annunci dei tuoi concorrenti
- Monitoraggio del brand: traccia i tuoi account ufficiali e quelli dei tuoi ambassador
- Analisi degli influencer: aggrega le opinioni di un panel di esperti
- Tracciamento istituzionale: segui gli account di enti regolatori o organizzazioni ufficiali
Utilizzo di excluded_x_handles (blocklist)
Questo parametro ti permette di escludere determinati account, come bot o account irrilevanti:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="What do developers think about the latest version of Python?",
tools=[{
"type": "x_search",
"excluded_x_handles": ["bot_python_news", "spam_account"]
}]
)
Casi d’uso della blocklist
- Escludere i bot: rimuovi gli account automatizzati dai risultati
- Escludere lo spam: filtra gli account noti per contenuti di bassa qualità
- Escludere i propri account: analizza le reazioni esterne senza includere i tuoi post
Sintassi SDK
xAI SDK (Python)
from xai_sdk.tools import x_search
tools=[x_search(
allowed_x_handles=["elonmusk", "xaboratory"]
)]
OpenAI SDK (Python)
tools=[{
"type": "x_search",
"allowed_x_handles": ["elonmusk", "xaboratory"]
}]
Vercel AI SDK (JavaScript)
tools: [xai.tools.xSearch({
allowedXHandles: ["elonmusk", "xaboratory"]
})]
Nota la convenzione camelCase nell’SDK JavaScript: allowedXHandles invece di allowed_x_handles.
Best practices
Scegliere tra allowlist e blocklist
Usa l’allowlist quando hai un insieme definito di account e desideri solo i loro post. Questo è il metodo più preciso ed efficiente in termini di token.
Usa la blocklist quando vuoi effettuare una ricerca ampia ma necessiti di ripulirla eliminando fonti di rumore note.
Ottimizzare il numero di handle
Con un limite di 10 handle, sii selettivo. Se devi monitorare più di 10 account, raggruppa le richieste per argomento o effettua chiamate sequenziali multiple.
Formato dell’handle
Gli handle non includono il simbolo @ (ad esempio, xaboratory). Verifica che gli handle siano corretti: un handle scritto male restituirà semplicemente nessun risultato per quell’account.
Punti chiave
- Due parametri:
allowed_x_handles(allowlist) edexcluded_x_handles(blocklist) - Mutuamente esclusivi: solo uno alla volta per richiesta
- Massimo 10 handle per parametro
- Gli handle si scrivono senza la
@:"elonmusk", non"@elonmusk" - Ideali per monitoraggio, tracciamento del brand e analisi degli influencer