# X-gegevens

Haal X-profielen op, zoek gebruikers en berichten, en pagineer tijdlijnen en antwoorden.

Kies de bewerking voor de gegevens die je nodig hebt. Alle vijf eindpunten gebruiken POST en retourneren JSON op de root, zonder een algemene `data`-wrapper.

Alle voorbeelden gebruiken `FELO_API_KEY` uit het [overzicht](https://openapi.felo.ai/nl/docs/data-api/guides/felo-overview.md). Aanroepen gebruiken **platformsaldo**, niet Felo Pro-credits. Reactievoorbeelden zijn illustratief; live inhoud en optionele velden kunnen variëren.

## Kies een bewerking

| Nodig | Eindpunt |
|---|---|
| Profielen voor bekende gebruikersnamen | `POST /api/v1/data/x/user/info` |
| Vind gebruikers via een zoekopdracht | `POST /api/v1/data/x/user/search` |
| Berichten van één gebruiker | `POST /api/v1/data/x/user/tweets` |
| Berichten die overeenkomen met een zoekopdracht | `POST /api/v1/data/x/tweet/search` |
| Antwoorden op bekende berichten | `POST /api/v1/data/x/tweet/replies` |

## 1. Gebruikersprofielen ophalen

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

| Veld | Type | Vereist | Betekenis |
|---|---|---|---|
| `usernames` | string array | Ja | 1–100 gebruikersnamen; stuur handles zonder `@` |

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

De reactie bevat `users` en `total`. Elke gebruiker bevat `user_id`, `username` en `display_name`; profieltekst, volgersaantallen, verificatie en andere metadata kunnen ook aanwezig zijn. Een batch kan minder profielen teruggeven dan gevraagd. Match op gebruikersnaam of ID, niet op arraypositie.

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

## 2. Gebruikers zoeken

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

| Veld | Type | Vereist | Betekenis |
|---|---|---|---|
| `query` | string | Ja | 1–1.000 tekens |
| `cursor` | string | Nee | Paginatiecursor, tot 4.000 tekens |

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

De reactie bevat `users`, `total`, `has_next` en `next_cursor`. Er is geen `limit`-parameter voor deze bewerking.

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

## 3. Gebruikerstijdlijn ophalen

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

| Veld | Type | Vereist | Betekenis |
|---|---|---|---|
| `username` | string | Eén identificatie vereist | Gebruikersnaam, tot 100 tekens |
| `x_user_id` | string | Eén identificatie vereist | Gebruikers-ID, tot 100 tekens; heeft voorrang op `username` |
| `limit` | integer | Nee | 1–1.000; huidige implementatie gebruikt minimaal 20, met standaard 20 |
| `cursor` | string | Nee | Paginatiecursor, tot 4.000 tekens |
| `include_replies` | boolean | Nee | Geneste antwoorden opnemen; standaard `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}'
```

De reactie bevat `tweets`, `total`, `has_next` en `next_cursor`. Door `limit` lager dan 20 in te stellen, krijg je niet noodzakelijk minder teruggegeven items of een kleinere factuur. Antwoorden opnemen kan meer teruggegeven gegevens en factureerbare resultaten toevoegen.

### Limieten voor resultaat en geneste antwoorden

`limit` is het doel aantal topniveau-berichten voor dit verzoek, niet een gegarandeerd resultaataantal. De huidige implementatie gebruikt een doel van minstens 20: een doel van 20 leest één upstream-pagina; grotere doelen halen automatisch tot 50 pagina's op. Vóór elke pagina wordt de verstreken tijd gecontroleerd en er wordt gestopt met ophalen zodra deze 60 seconden overschrijdt. Deze controle garandeert niet dat het volledige HTTP-verzoek binnen 60 seconden eindigt.

Verzameling stopt ook wanneer het doel is bereikt, de upstream geen volgende pagina heeft, een pagina leeg is of de cursor ontbreekt. Een succesvolle reactie kan dus minder dan `limit` berichten bevatten. Gebruik `has_next` en `next_cursor` om door te gaan wanneer beschikbaar.

Met `include_replies=true` krijgt elk teruggegeven bericht tot 5 extra pagina's en maximaal 100 geneste antwoorden. Verzameling kan eerder stoppen wanneer er geen volgende pagina is, een pagina leeg is of de cursor niet kan verdergaan. Deze geneste antwoorden vallen buiten de topniveau-`limit` en `total`, maar kunnen wel factureerbare resultaten toevoegen.

Geneste `replies` zijn geen volledig antwoordarchief en geven geen aparte vervolgcursor voor deze extra verzameling weer. Om antwoorden onafhankelijk te pagineren, gebruik je de bewerking Antwoorden lezen en de teruggegeven cursor. Hergebruik niet de topniveau-berichtcursor voor antwoorden.

## 4. Berichten zoeken

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

| Veld | Type | Vereist | Betekenis |
|---|---|---|---|
| `query` | string | Ja | Zoektekst, 1–1.000 tekens |
| `query_type` | string | Nee | `Latest` (standaard) of `Top` |
| `limit` | integer | Nee | 1–1.000; huidige implementatie gebruikt minimaal 20, met standaard 20 |
| `cursor` | string | Nee | Paginatiecursor, tot 4.000 tekens |
| `since_time` | integer or string | Nee | Begintijd; gebruik Unix-seconden voor een ondubbelzinnige numerieke waarde |
| `until_time` | integer or string | Nee | Eindtijd; gebruik Unix-seconden, geen milliseconden |

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

De reactie bevat `tweets`, `total`, `has_next` en `next_cursor`. Berichtobjecten bevatten `id`, `content`, `author`, `created_at` en `metrics`; antwoorden en geciteerde/geretweete berichten kunnen genest zijn. Behandel ID's als strings.

### Limieten voor aantal resultaten

`limit` is een doel, geen garantie. De huidige implementatie gebruikt een doel van minstens 20: een doel van 20 leest één upstream-pagina; grotere doelen halen automatisch tot 50 pagina's op. Verstreken tijd wordt vóór elke pagina gecontroleerd en er worden geen verdere pagina's opgehaald zodra dit meer dan 60 seconden is. Een lopend upstream-verzoek kan nog steeds tijd kosten, dus dit is geen algemene HTTP-time-out.

Verzameling stopt ook wanneer het doel is bereikt, de upstream geen volgende pagina heeft, een pagina leeg is of de cursor ontbreekt. Minder dan `limit` berichten teruggeven betekent niet dat het verzoek is mislukt of dat elk overeenkomend bericht is opgehaald. Controleer `has_next` en `next_cursor` voordat je doorgaat.

```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. Antwoorden lezen

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

| Veld | Type | Vereist | Betekenis |
|---|---|---|---|
| `tweet_ids` | string of string array | Ja | Eén bericht-ID of een batch van maximaal 20 ID's |
| `cursor` | string | Nee | Tot 4.000 tekens; gebruik met één bericht-ID |
| `since_time` | integer | Nee | Begintijd in Unix-seconden |
| `until_time` | integer | Nee | Eindtijd in Unix-seconden |

Vervang de tijdelijke aanduiding door een echte bericht-ID:

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

In tegenstelling tot de tijdlijn- en berichtzoekopdracht worden antwoorden gegroepeerd onder `results`. Elke invoer heeft een eigen paginatiestatus:

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

### Antwoordlimieten per verzoek

Elk verzoek leest één upstream-antwoordpagina per `tweet_id` en behoudt maximaal 100 antwoorden; het haalt niet automatisch elke antwoordpagina op. In een batch van maximaal 20 ID's geldt de limiet van 100 antwoorden afzonderlijk voor elke `results`-invoer. Werkelijke aantallen kunnen lager zijn.

De `total` van elke invoer is het aantal antwoorden dat in die invoer is teruggegeven, niet het volledige antwoordaantal van het bericht. Om door te gaan, gebruik je de `next_cursor` van die invoer en stuur je in het volgende verzoek alleen de enkele bericht-ID. Er is geen `limit`-parameter om de limiet per verzoek te verhogen.

## Paginering en kostenbeheersing

`total` telt de overeenkomstige array in de huidige reactie: berichten op topniveau voor berichtquery's, of antwoorden binnen elke resultaatinvoer voor antwoordquery's. Het is geen globaal matchaantal, geen volledig antwoordaantal van een bericht en geen uiteindelijke factureerbare telling.

1. Stuur het eerste verzoek zonder `cursor`.
2. Lees `has_next` en `next_cursor` uit de reactie. Voor antwoorden lees je ze in elke resultaatinvoer.
3. Als er nog een pagina is en de cursor niet leeg is, stuur je die ongewijzigd mee met dezelfde query. Voor een antwoordenbatch ga je per bericht afzonderlijk verder.
4. Stop wanneer er geen volgende pagina is, wanneer een cursor zich herhaalt, of wanneer je eigen pagina- of bestedingslimiet is bereikt.

Paginatiemetagegevens weerspiegelen de laatste upstream-reactie; de teruggegeven verzameling kan worden afgekapt bij een resultaatlimiet. Zelfs `has_next=false` is geen garantie dat alle X-geschiedenis of antwoorden zijn opgehaald. Geef het daadwerkelijk teruggegeven aantal weer in plaats van een begrensde resultaatset als alle beschikbare gegevens te labelen.

Elke succesvolle pagina kan kosten met zich meebrengen. Deze vijf bewerkingen worden gefactureerd op basis van teruggegeven resultaten, niet per vaste verzoekprijs. Geneste antwoorden en andere teruggegeven records kunnen de gefactureerde telling beïnvloeden; schat de kosten niet alleen op basis van de lengte van de array op topniveau. Controleer de [huidige prijzen](https://openapi.felo.ai/api/v1/data/prices) en het gebruik in de console. Volledige objectvelden staan in het [OpenAPI-schema](https://openapi.felo.ai/api/v1/data/openapi.json).