# X-Daten

Rufe X-Profile ab, suche Nutzer und Beiträge und paginiere Timelines und Antworten.

Wähle die Operation für die Daten, die du benötigst. Alle fünf Endpunkte verwenden POST und geben JSON an der Root zurück, ohne einen gemeinsamen `data`-Wrapper.

Alle Beispiele verwenden `FELO_API_KEY` aus der [Übersicht](https://openapi.felo.ai/de/docs/data-api/guides/felo-overview.md). Aufrufe verwenden **Plattform-Guthaben**, nicht Felo-Pro-Guthaben. Antwortbeispiele sind illustrativ; Live-Inhalte und optionale Felder variieren.

## Wähle eine Operation

| Bedarf | Endpunkt |
|---|---|
| Profile für bekannte Benutzernamen | `POST /api/v1/data/x/user/info` |
| Nutzer über eine Suchanfrage finden | `POST /api/v1/data/x/user/search` |
| Beiträge eines Nutzers | `POST /api/v1/data/x/user/tweets` |
| Beiträge, die einer Anfrage entsprechen | `POST /api/v1/data/x/tweet/search` |
| Antworten auf bekannte Beiträge | `POST /api/v1/data/x/tweet/replies` |

## 1. Nutzerprofile abrufen

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

| Feld | Typ | Erforderlich | Bedeutung |
|---|---|---|---|
| `usernames` | string array | Ja | 1–100 Benutzernamen; Handles ohne `@` senden |

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

Die Antwort enthält `users` und `total`. Jeder Nutzer umfasst `user_id`, `username` und `display_name`; Profiltext, Follower-Zahlen, Verifizierung und andere Metadaten können ebenfalls vorhanden sein. Eine Batch kann weniger Profile zurückgeben als angefordert. Abgleichen nach Benutzername oder ID, nicht nach Array-Position.

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

## 2. Nutzer suchen

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

| Feld | Typ | Erforderlich | Bedeutung |
|---|---|---|---|
| `query` | string | Ja | 1–1.000 Zeichen |
| `cursor` | string | Nein | Paginierungscursor, bis zu 4.000 Zeichen |

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

Die Antwort enthält `users`, `total`, `has_next` und `next_cursor`. Für diese Operation gibt es keinen `limit`-Parameter.

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

## 3. Eine Nutzer-Timeline abrufen

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

| Feld | Typ | Erforderlich | Bedeutung |
|---|---|---|---|
| `username` | string | Ein Bezeichner erforderlich | Nutzer-Handle, bis zu 100 Zeichen |
| `x_user_id` | string | Ein Bezeichner erforderlich | Nutzer-ID, bis zu 100 Zeichen; hat Vorrang vor `username` |
| `limit` | integer | Nein | 1–1.000; die aktuelle Implementierung verwendet mindestens 20, Standard 20 |
| `cursor` | string | Nein | Paginierungscursor, bis zu 4.000 Zeichen |
| `include_replies` | boolean | Nein | Eingebettete Antworten einschließen; Standard `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}'
```

Die Antwort enthält `tweets`, `total`, `has_next` und `next_cursor`. Das Setzen von `limit` unter 20 gewährleistet nicht, dass weniger Elemente zurückgegeben werden oder eine kleinere Gebühr anfällt. Das Einschließen von Antworten kann zusätzliche zurückgegebene Daten und abrechenbare Ergebnisse hinzufügen.

### Ergebnis- und Limits für verschachtelte Antworten

`limit` ist die Zielanzahl der Top-Level-Beiträge für diese Anfrage, nicht eine garantierte Ergebniszahl. Die aktuelle Implementierung verwendet ein Ziel von mindestens 20: Ein Ziel von 20 liest eine Upstream-Seite; größere Ziele holen automatisch bis zu 50 Seiten ab. Vor jeder Seite wird die verstrichene Zeit geprüft, und weitere Seiten werden nicht mehr abgerufen, sobald sie 60 Sekunden überschreitet. Diese Prüfung ist keine Garantie dafür, dass die gesamte HTTP-Anfrage innerhalb von 60 Sekunden abgeschlossen wird.

Die Sammlung stoppt außerdem, wenn das Ziel erreicht ist, der Upstream keine nächste Seite hat, eine Seite leer ist oder der Cursor fehlt. Eine erfolgreiche Antwort kann daher weniger als `limit` Beiträge enthalten. Verwende `has_next` und `next_cursor`, um fortzufahren, wenn sie verfügbar sind.

Bei `include_replies=true` erhält jeder zurückgegebene Beitrag bis zu 5 zusätzliche Seiten und höchstens 100 verschachtelte Antworten. Die Sammlung kann früher stoppen, wenn es keine nächste Seite gibt, eine Seite leer ist oder der Cursor nicht fortschreiten kann. Diese verschachtelten Antworten liegen außerhalb von Top-Level-`limit` und `total`, können aber abrechenbare Ergebnisse hinzufügen.

Verschachtelte `replies` sind kein vollständiges Antwortarchiv und stellen keinen separaten Fortsetzungscursor für diese zusätzliche Sammlung bereit. Um Antworten unabhängig zu paginieren, verwende die Operation Zum Lesen von Antworten und den zurückgegebenen Cursor. Verwende für Antworten nicht den Top-Level-Beitragscursor erneut.

## 4. Beiträge suchen

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

| Feld | Typ | Erforderlich | Bedeutung |
|---|---|---|---|
| `query` | string | Ja | Suchtext, 1–1.000 Zeichen |
| `query_type` | string | Nein | `Latest` (Standard) oder `Top` |
| `limit` | integer | Nein | 1–1.000; die aktuelle Implementierung verwendet mindestens 20, Standard 20 |
| `cursor` | string | Nein | Paginierungscursor, bis zu 4.000 Zeichen |
| `since_time` | integer or string | Nein | Startzeit; verwende Unix-Sekunden für einen eindeutigen numerischen Wert |
| `until_time` | integer or string | Nein | Endzeit; verwende Unix-Sekunden, nicht Millisekunden |

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

Die Antwort enthält `tweets`, `total`, `has_next` und `next_cursor`. Beitragsobjekte enthalten `id`, `content`, `author`, `created_at` und `metrics`; Antworten und zitierte/weitergeleitete Beiträge können verschachtelt sein. Behandle IDs als Strings.

### Limits für die Ergebnisanzahl

`limit` ist ein Ziel, keine Garantie. Die aktuelle Implementierung verwendet ein Ziel von mindestens 20: Ein Ziel von 20 liest eine Upstream-Seite; größere Ziele holen automatisch bis zu 50 Seiten ab. Vor jeder Seite wird die verstrichene Zeit geprüft, und sobald sie 60 Sekunden überschreitet, werden keine weiteren Seiten abgerufen. Eine laufende Upstream-Anfrage kann trotzdem Zeit benötigen, daher ist dies kein gesamter HTTP-Timeout.

Die Sammlung stoppt außerdem, wenn das Ziel erreicht ist, der Upstream keine nächste Seite hat, eine Seite leer ist oder der Cursor fehlt. Weniger als `limit` Beiträge zurückzugeben bedeutet nicht, dass die Anfrage fehlgeschlagen ist oder dass jeder passende Beitrag abgerufen wurde. Prüfe vor dem Fortfahren `has_next` und `next_cursor`.

```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. Antworten lesen

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

| Feld | Typ | Erforderlich | Bedeutung |
|---|---|---|---|
| `tweet_ids` | string or string array | Ja | Eine Beitrags-ID oder eine Batch von bis zu 20 IDs |
| `cursor` | string | Nein | Bis zu 4.000 Zeichen; zusammen mit einer Beitrags-ID verwenden |
| `since_time` | integer | Nein | Startzeit in Unix-Sekunden |
| `until_time` | integer | Nein | Endzeit in Unix-Sekunden |

Ersetze den Platzhalter durch eine echte Beitrags-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"]}'
```

Im Gegensatz zur Timeline- und Beitragssuche werden Antworten unter `results` gruppiert. Jeder Eintrag hat seinen eigenen Paginierungsstatus:

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

### Antwortlimits pro Anfrage

Jede Anfrage liest eine Upstream-Antwortseite pro `tweet_id` und behält höchstens 100 Antworten; sie ruft nicht automatisch jede Antwortseite ab. In einer Batch von bis zu 20 IDs gilt die 100-Antworten-Grenze getrennt für jeden `results`-Eintrag. Tatsächliche Anzahlen können niedriger sein.

Das `total` jedes Eintrags ist die Anzahl der in diesem Eintrag zurückgegebenen Antworten, nicht die vollständige Antwortanzahl des Beitrags. Um fortzufahren, verwende den `next_cursor` dieses Eintrags und sende in der nächsten Anfrage nur dessen einzelne Beitrags-ID. Es gibt keinen `limit`-Parameter, um die Obergrenze pro Anfrage zu erhöhen.

## Paginierung und Kostenkontrolle

`total` zählt das entsprechende Array in der aktuellen Antwort: Top-Level-Beiträge für Beitragsanfragen oder Antworten innerhalb jedes Ergebniseintrags für Antwortanfragen. Es ist keine globale Trefferanzahl, keine vollständige Antwortanzahl eines Beitrags und nicht die endgültig abrechenbare Anzahl.

1. Sende die erste Anfrage ohne `cursor`.
2. Lies `has_next` und `next_cursor` aus der Antwort. Bei Antworten lies sie in jedem Ergebniseintrag.
3. Wenn eine weitere Seite existiert und der Cursor nicht leer ist, sende ihn unverändert mit derselben Anfrage. Für eine Antworten-Batch fahre für jeden Beitrag separat fort.
4. Stoppe, wenn es keine nächste Seite gibt, wenn sich ein Cursor wiederholt oder wenn deine eigene Seiten- oder Ausgabenobergrenze erreicht ist.

Die Paginierungsmetadaten spiegeln die letzte Upstream-Antwort wider; die zurückgegebene Sammlung kann bei einer Ergebnisobergrenze abgeschnitten sein. Selbst `has_next=false` ist keine Garantie dafür, dass die gesamte X-Historie oder alle Antworten abgerufen wurden. Zeige die tatsächlich zurückgegebene Anzahl an, statt einen begrenzten Ergebnissatz als alle verfügbaren Daten zu kennzeichnen.

Jede erfolgreiche Seite kann eine Gebühr verursachen. Diese fünf Operationen werden nach zurückgegebenen Ergebnissen und nicht mit einer pauschalen Anfragegebühr abgerechnet. Verschachtelte Antworten und andere zurückgegebene Datensätze können die abgerechnete Anzahl beeinflussen; schätze die Kosten nicht allein anhand der Länge des Top-Level-Arrays. Prüfe die [aktuellen Preise](https://openapi.felo.ai/api/v1/data/prices) und die Nutzung in der Konsole. Vollständige Objektfelder stehen im [OpenAPI-Schema](https://openapi.felo.ai/api/v1/data/openapi.json).