# Dati X

Recupera profili X, cerca utenti e post e pagine cronologie e risposte.

Scegli l'operazione per i dati di cui hai bisogno. Tutti e cinque gli endpoint usano POST e restituiscono JSON alla radice, senza un wrapper comune `data`.

Tutti gli esempi usano `FELO_API_KEY` dalla [panoramica](https://openapi.felo.ai/it/docs/data-api/guides/felo-overview.md). Le chiamate usano **il saldo della piattaforma**, non i crediti Felo Pro. Gli esempi di risposta sono illustrativi; il contenuto live e i campi opzionali variano.

## Scegli un'operazione

| Necessità | Endpoint |
|---|---|
| Profili per username noti | `POST /api/v1/data/x/user/info` |
| Trova utenti tramite una query di ricerca | `POST /api/v1/data/x/user/search` |
| Post di un utente | `POST /api/v1/data/x/user/tweets` |
| Post che corrispondono a una query | `POST /api/v1/data/x/tweet/search` |
| Risposte a post noti | `POST /api/v1/data/x/tweet/replies` |

## 1. Ottieni profili utente

`POST /api/v1/data/x/user/info`

| Campo | Tipo | Obbligatorio | Significato |
|---|---|---|---|
| `usernames` | array di stringhe | Sì | 1–100 username; invia gli handle senza `@` |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/info" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["OpenAI"]}'
```

La risposta contiene `users` e `total`. Ogni utente include `user_id`, `username` e `display_name`; possono essere presenti anche testo del profilo, conteggi dei follower, verifica e altri metadati. Un batch può restituire meno profili di quelli richiesti. Abbina per username o ID, non per posizione nell'array.

```json
{"users":[{"user_id":"example-user-id","username":"example","display_name":"Example"}],"total":1}
```

## 2. Cerca utenti

`POST /api/v1/data/x/user/search`

| Campo | Tipo | Obbligatorio | Significato |
|---|---|---|---|
| `query` | string | Sì | 1–1.000 caratteri |
| `cursor` | string | No | Cursor di paginazione, fino a 4.000 caratteri |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"AI research"}'
```

La risposta contiene `users`, `total`, `has_next` e `next_cursor`. Non esiste un parametro `limit` per questa operazione.

```json
{"users":[],"total":0,"has_next":false,"next_cursor":null}
```

## 3. Ottieni la timeline di un utente

`POST /api/v1/data/x/user/tweets`

| Campo | Tipo | Obbligatorio | Significato |
|---|---|---|---|
| `username` | string | È richiesto un identificatore | Handle utente, fino a 100 caratteri |
| `x_user_id` | string | È richiesto un identificatore | ID utente, fino a 100 caratteri; ha la precedenza su `username` |
| `limit` | integer | No | 1–1.000; l'implementazione attuale usa almeno 20, con predefinito 20 |
| `cursor` | string | No | Cursor di paginazione, fino a 4.000 caratteri |
| `include_replies` | boolean | No | Includi risposte annidate; predefinito `false` |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/tweets" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"OpenAI","limit":20,"include_replies":false}'
```

La risposta contiene `tweets`, `total`, `has_next` e `next_cursor`. Impostare `limit` sotto 20 non garantisce meno elementi restituiti o un addebito minore. Includere le risposte può aggiungere dati restituiti e risultati fatturabili.

### Limiti dei risultati e delle risposte annidate

`limit` è il numero obiettivo di post di primo livello per questa richiesta, non un conteggio garantito dei risultati. L'implementazione attuale usa un obiettivo di almeno 20: un obiettivo di 20 legge una pagina upstream; obiettivi più grandi recuperano automaticamente fino a 50 pagine. Prima di ogni pagina, controlla il tempo trascorso e interrompe il recupero di altre pagine una volta superati i 60 secondi. Questo controllo non garantisce che l'intera richiesta HTTP termini entro 60 secondi.

La raccolta si interrompe anche quando l'obiettivo viene raggiunto, l'upstream non ha una pagina successiva, una pagina è vuota o il cursor manca. Una risposta riuscita può quindi contenere meno di `limit` post. Usa `has_next` e `next_cursor` per continuare quando disponibili.

Con `include_replies=true`, ogni post restituito ottiene fino a 5 pagine extra e al massimo 100 risposte annidate. La raccolta può interrompersi prima quando non c'è una pagina successiva, una pagina è vuota o il cursor non può avanzare. Queste risposte annidate sono esterne al `limit` e al `total` di primo livello, ma possono aggiungere risultati fatturabili.

Le `replies` annidate non sono un archivio completo delle risposte e non espongono un cursor di continuazione separato per questa raccolta aggiuntiva. Per paginare le risposte in modo indipendente, usa l'operazione Read replies e il cursor che restituisce. Non riutilizzare il cursor del post di primo livello per le risposte.

## 4. Cerca post

`POST /api/v1/data/x/tweet/search`

| Campo | Tipo | Obbligatorio | Significato |
|---|---|---|---|
| `query` | string | Sì | Testo di ricerca, 1–1.000 caratteri |
| `query_type` | string | No | `Latest` (predefinito) o `Top` |
| `limit` | integer | No | 1–1.000; l'implementazione attuale usa almeno 20, con predefinito 20 |
| `cursor` | string | No | Cursor di paginazione, fino a 4.000 caratteri |
| `since_time` | integer or string | No | Ora di inizio; usa secondi Unix per un valore numerico non ambiguo |
| `until_time` | integer or string | No | Ora di fine; usa secondi Unix, non millisecondi |

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/tweet/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"retrieval augmented generation","query_type":"Latest","limit":20}'
```

La risposta contiene `tweets`, `total`, `has_next` e `next_cursor`. Gli oggetti post includono `id`, `content`, `author`, `created_at` e `metrics`; risposte e post citati/ritwittati possono essere annidati. Tratta gli ID come stringhe.

### Limiti del numero di risultati

`limit` è un obiettivo, non una garanzia. L'implementazione attuale usa un obiettivo di almeno 20: un obiettivo di 20 legge una pagina upstream; obiettivi più grandi recuperano automaticamente fino a 50 pagine. Il tempo trascorso viene controllato prima di ogni pagina e non vengono recuperate altre pagine una volta superati 60 secondi. Una richiesta upstream in corso può comunque richiedere tempo, quindi questo non è un timeout HTTP complessivo.

La raccolta si interrompe anche quando l'obiettivo viene raggiunto, l'upstream non ha una pagina successiva, una pagina è vuota o il cursor manca. Restituire meno di `limit` post non significa che la richiesta sia fallita o che ogni post corrispondente sia stato recuperato. Controlla `has_next` e `next_cursor` prima di continuare.

```json
{
  "tweets": [{
    "id":"example-post-id",
    "content":"Example post content",
    "author":{"user_id":"example-user-id","username":"example","display_name":"Example"},
    "created_at":"2026-11-01T00:00:00Z",
    "metrics":{},
    "replies":[]
  }],
  "total":1,
  "has_next":false,
  "next_cursor":null
}
```

## 5. Leggi le risposte

`POST /api/v1/data/x/tweet/replies`

| Campo | Tipo | Obbligatorio | Significato |
|---|---|---|---|
| `tweet_ids` | string o array di stringhe | Sì | Un ID post oppure un batch di fino a 20 ID |
| `cursor` | string | No | Fino a 4.000 caratteri; usa con un solo ID post |
| `since_time` | integer | No | Ora di inizio in secondi Unix |
| `until_time` | integer | No | Ora di fine in secondi Unix |

Sostituisci il segnaposto con un vero ID post:

```bash
curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/tweet/replies" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tweet_ids":["POST_ID"]}'
```

A differenza della timeline e della ricerca post, le risposte sono raggruppate sotto `results`. Ogni voce ha il proprio stato di paginazione:

```json
{"results":[{"tweet_id":"POST_ID","replies":[],"total":0,"has_next":false,"next_cursor":null}]}
```

### Limiti delle risposte per richiesta

Ogni richiesta legge una pagina di risposte upstream per ogni `tweet_id` e conserva al massimo 100 risposte; non recupera automaticamente ogni pagina di risposte. In un batch di fino a 20 ID, il limite di 100 risposte si applica separatamente a ciascuna voce `results`. I conteggi effettivi possono essere inferiori.

Il `total` di ogni voce è il numero di risposte restituite in quella voce, non il conteggio completo delle risposte del post. Per continuare, usa il `next_cursor` di quella voce e invia solo il suo singolo ID post nella richiesta successiva. Non esiste un parametro `limit` per aumentare il limite per richiesta.

## Paginazione e controllo dei costi

`total` conta l'array corrispondente nella risposta corrente: post di primo livello per le query sui post, o risposte all'interno di ciascuna voce risultato per le query sulle risposte. Non è un conteggio globale delle corrispondenze, né il conteggio completo delle risposte di un post, né il conteggio finale fatturabile.

1. Invia la prima richiesta senza `cursor`.
2. Leggi `has_next` e `next_cursor` dalla risposta. Per le risposte, leggili in ogni voce risultato.
3. Se esiste un'altra pagina e il cursor non è vuoto, invialo invariato con la stessa query. Per un batch di risposte, continua separatamente per ogni post.
4. Fermati quando non c'è più una pagina successiva, quando un cursor si ripete o quando raggiungi il tuo limite di pagine o di spesa.

I metadati di paginazione riflettono l'ultima risposta upstream; la raccolta restituita può essere troncata da un limite di risultati. Anche `has_next=false` non garantisce che tutta la cronologia X o tutte le risposte siano state recuperate. Mostra il conteggio effettivo restituito invece di etichettare un insieme di risultati limitato come tutti i dati disponibili.

Ogni pagina riuscita può comportare un addebito. Queste cinque operazioni sono fatturate in base ai risultati restituiti, non con una tariffa fissa per richiesta. Le risposte annidate e altri record restituiti possono influire sul conteggio fatturato; non stimare il costo solo dalla lunghezza dell'array di primo livello. Controlla i [prezzi attuali](https://openapi.felo.ai/api/v1/data/prices) e l'utilizzo nella console. I campi completi degli oggetti sono nello [schema OpenAPI](https://openapi.felo.ai/api/v1/data/openapi.json).