Ottenere dati pubblici dei profili X con Python per il lead enrichment

Prima di scrivere a un creator o aggiungere un lead a una lista, vuoi le basi: quanti follower ha davvero, l’account è verificato, cosa dice la bio, quando è stato creato. Questo è un lookup su un profilo pubblico, non un progetto di ricerca, e /v1/x risponde esattamente a questo con una richiesta.

La piattaforma sviluppatori di X può rispondere alla stessa domanda, ma solo dopo che registri un’app, vieni approvato, e scegli un piano a pagamento, un costo di setup vero se tutto quello che ti serve è un conteggio follower su una manciata di lead a settimana. Questo endpoint salta tutto questo: è una normale chiamata REST su dati di profilo pubblici, fatturata per lookup invece che per abbonamento.

Un solo parametro: profileId

L’unico parametro è profileId, in camelCase, ed è lo username senza la @. Passa elonmusk, non @elonmusk e non un URL di profilo. Se la tua lista sorgente ha username copiati direttamente da X o da un link di profilo, togli la @ e qualunque URL attorno prima di costruire la richiesta, dato che profileId è documentato come semplice handle, senza altro.

import requests

API_KEY = "faf_live_..."  # la tua chiave FastAF

resp = requests.get(
    "https://api.fastaf.co/v1/x",
    params={"profileId": "elonmusk"},
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=60,
)
resp.raise_for_status()

profile = resp.json()["profile"]
stats = profile["stats"]

print(f'{profile["name"]} ({profile["username"]})')
print(f'verified: {profile["is_blue_verified"]}')
print(f'followers: {stats["followers"]:,}  following: {stats["following"]:,}  tweets: {stats["tweets"]:,}')
print(f'bio: {profile["description"]}')
print(f'created: {profile["created_at"]}')

Questo costa 5 crediti. Tutto si annida prima sotto un oggetto profile, e i contatori si annidano di nuovo un livello più in profondità sotto profile["stats"], che è la parte che le persone indovinano sbagliata prima di controllare: followers non è di primo livello.

Cosa ottieni davvero

Eseguire la chiamata sopra contro un account reale e conosciuto ha restituito un oggetto profile con: name, username (questo torna con la @ inclusa, anche se il parametro della richiesta non la prende), user_id, description (la bio), location, website, created_at, is_blue_verified, verified_type, protected, possibly_sensitive, e campi immagine (profile_image, profile_banner). Annidati sotto stats: followers, following, tweets, e creator_subscriptions. Per quell’account specifico i numeri erano un conteggio followers sopra i 241 milioni, following a 1.396, e tweets a 107.673, tutti interi semplici, niente formattazione da rimuovere. È abbastanza per costruire una vera regola di vetting, per esempio rifiutare qualunque cosa sotto una soglia minima di follower, o un controllo sull’età dell’account calcolato da created_at.

location è tornato null su questo account, il che ricorda che i campi del profilo sono completi solo quanto quello che la persona ha compilato su X: tratta ogni campo tranne le basi identitarie (name, username, user_id) come opzionale quando scrivi il codice che consuma questi dati.

Cosa non fa

Sii chiaro con te stesso sull’ambito prima di costruirci sopra una pipeline: /v1/x restituisce un profilo, una volta, per chiamata. Non restituisce i post di quell’account, non restituisce una lista dei suoi follower o di chi segue, e non è una ricerca: ti serve già lo username esatto, da un form lead, un CSV, una menzione, da qualunque parte venga la tua lista. Se il tuo workflow ha bisogno di “trova account che parlano di X” invece di “dimmi di questo account specifico”, questo endpoint è lo strumento sbagliato per quel passaggio.

È anche uno snapshot, non un abbonamento: niente ti manda un aggiornamento quando un conteggio follower supera una soglia o una bio cambia. Se ti serve questo, richiamalo sul tuo schedule e confronta gli stats che ricevi con quello che avevi salvato l’ultima volta, allo stesso modo in cui tracceresti qualunque altro numero che cambia nel tempo.

Vetting ed enrichment, in concreto

Il pattern comune è un job in batch: una lista di username in ingresso, una lista filtrata o punteggiata in uscita. Tieni il filtro stesso semplice e specifico per quello che ti serve davvero, una soglia minima di follower, un controllo di verifica, un taglio sull’età dell’account, invece di provare a calcolare un unico “influencer score” da campi che non sono mai stati pensati per essere combinati in uno solo.

def enrich(usernames, min_followers=10_000):
    qualified = []
    for handle in usernames:
        resp = requests.get(
            "https://api.fastaf.co/v1/x",
            params={"profileId": handle},
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=60,
        )
        resp.raise_for_status()
        p = resp.json()["profile"]
        if p["stats"]["followers"] >= min_followers:
            qualified.append({
                "username": p["username"],
                "followers": p["stats"]["followers"],
                "verified": p["is_blue_verified"],
                "bio": p["description"],
            })
    return qualified

Avvolgi ogni chiamata in un try/except in produzione: un account disattivato o sospeso è una possibilità reale in qualunque lista che non hai generato tu stesso, e vuoi che questo salti una riga, non che fermi il batch.

Quanto costa

Volume	Crediti	Pacchetto che lo copre	Costo
500 lead, un giro di vetting una tantum	2.500	Growth, $29	~$0,97 del pacchetto
5.000 profili arricchiti in 30 giorni	25.000	Growth, $29	~$9,67 del pacchetto
50.000 profili arricchiti in 30 giorni	250.000	Scale, $99	~$82,50 del pacchetto

Le richieste fallite non vengono mai fatturate: i crediti vengono riservati quando una richiesta parte e restituiti se non torna con un risultato. Il piano gratuito è 500 crediti senza carta, che coprono 100 lookup di profilo, più che abbastanza per verificare la copertura dei campi sulla tua lista prima di impegnarti su uno schedule.