# Dane X

Pobieraj profile X, wyszukuj użytkowników i posty oraz stronicuj osie czasu i odpowiedzi.

Wybierz operację dla danych, których potrzebujesz. Wszystkie pięć punktów końcowych używa POST i zwraca JSON w korzeniu, bez wspólnego opakowania `data`.

Wszystkie przykłady używają `FELO_API_KEY` z [przeglądu](https://openapi.felo.ai/pl/docs/data-api/guides/felo-overview.md). Wywołania korzystają z **salda platformy**, a nie z kredytów Felo Pro. Przykłady odpowiedzi mają charakter poglądowy; rzeczywista treść i opcjonalne pola mogą się różnić.

## Wybierz operację

| Potrzeba | Punkt końcowy |
|---|---|
| Profile dla znanych nazw użytkowników | `POST /api/v1/data/x/user/info` |
| Znajdź użytkowników według zapytania | `POST /api/v1/data/x/user/search` |
| Posty jednego użytkownika | `POST /api/v1/data/x/user/tweets` |
| Posty pasujące do zapytania | `POST /api/v1/data/x/tweet/search` |
| Odpowiedzi na znane posty | `POST /api/v1/data/x/tweet/replies` |

## 1. Pobierz profile użytkowników

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

| Pole | Typ | Wymagane | Znaczenie |
|---|---|---|---|
| `usernames` | tablica stringów | Tak | 1–100 nazw użytkowników; podawaj uchwyty bez `@` |

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

Odpowiedź zawiera `users` i `total`. Każdy użytkownik zawiera `user_id`, `username` i `display_name`; tekst profilu, liczba obserwujących, weryfikacja i inne metadane również mogą być obecne. Partia może zwrócić mniej profili niż żądano. Dopasowuj po nazwie użytkownika lub ID, a nie po pozycji w tablicy.

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

## 2. Wyszukaj użytkowników

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

| Pole | Typ | Wymagane | Znaczenie |
|---|---|---|---|
| `query` | string | Tak | 1–1 000 znaków |
| `cursor` | string | Nie | Kursor stronicowania, do 4 000 znaków |

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

Odpowiedź zawiera `users`, `total`, `has_next` i `next_cursor`. W tej operacji nie ma parametru `limit`.

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

## 3. Pobierz oś czasu użytkownika

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

| Pole | Typ | Wymagane | Znaczenie |
|---|---|---|---|
| `username` | string | Wymagany jeden identyfikator | Nazwa użytkownika, do 100 znaków |
| `x_user_id` | string | Wymagany jeden identyfikator | ID użytkownika, do 100 znaków; ma pierwszeństwo przed `username` |
| `limit` | integer | Nie | 1–1 000; bieżąca implementacja używa co najmniej 20, z domyślną wartością 20 |
| `cursor` | string | Nie | Kursor stronicowania, do 4 000 znaków |
| `include_replies` | boolean | Nie | Uwzględnij zagnieżdżone odpowiedzi; domyślnie `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}'
```

Odpowiedź zawiera `tweets`, `total`, `has_next` i `next_cursor`. Ustawienie `limit` poniżej 20 nie gwarantuje mniejszej liczby zwróconych elementów ani niższej opłaty. Uwzględnienie odpowiedzi może dodać zwrócone dane i płatne wyniki.

### Limity wyników i zagnieżdżonych odpowiedzi

`limit` jest docelową liczbą postów najwyższego poziomu dla tego żądania, a nie gwarantowaną liczbą wyników. Bieżąca implementacja używa celu co najmniej 20: cel 20 odczytuje jedną nadrzędną stronę; większe cele automatycznie pobierają do 50 stron. Przed każdą stroną sprawdzany jest upływ czasu i pobieranie kolejnych stron zatrzymuje się po przekroczeniu 60 sekund. To sprawdzenie nie gwarantuje, że całe żądanie HTTP zakończy się w ciągu 60 sekund.

Zbieranie zatrzymuje się również, gdy osiągnięto cel, nadrzędne źródło nie ma następnej strony, strona jest pusta lub kursor jest brakujący. Udana odpowiedź może więc zawierać mniej niż `limit` postów. Użyj `has_next` i `next_cursor`, aby kontynuować, gdy są dostępne.

Przy `include_replies=true` każdy zwrócony post otrzymuje do 5 dodatkowych stron i maksymalnie 100 zagnieżdżonych odpowiedzi. Zbieranie może zakończyć się wcześniej, gdy nie ma następnej strony, strona jest pusta lub kursor nie może przejść dalej. Te zagnieżdżone odpowiedzi są poza górnym `limit` i `total`, ale mogą zwiększać liczbę wyników podlegających rozliczeniu.

Zagnieżdżone `replies` nie stanowią kompletnego archiwum odpowiedzi i nie udostępniają osobnego kursora kontynuacji dla tego dodatkowego zbierania. Aby stronicować odpowiedzi niezależnie, użyj operacji odczytu odpowiedzi i zwróconego przez nią kursora. Nie używaj ponownie kursora postu najwyższego poziomu do odpowiedzi.

## 4. Wyszukaj posty

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

| Pole | Typ | Wymagane | Znaczenie |
|---|---|---|---|
| `query` | string | Tak | Tekst wyszukiwania, 1–1 000 znaków |
| `query_type` | string | Nie | `Latest` (domyślnie) lub `Top` |
| `limit` | integer | Nie | 1–1 000; bieżąca implementacja używa co najmniej 20, z domyślną wartością 20 |
| `cursor` | string | Nie | Kursor stronicowania, do 4 000 znaków |
| `since_time` | integer or string | Nie | Czas początkowy; użyj sekund Unix dla jednoznacznej wartości liczbowej |
| `until_time` | integer or string | Nie | Czas końcowy; użyj sekund Unix, nie milisekund |

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

Odpowiedź zawiera `tweets`, `total`, `has_next` i `next_cursor`. Obiekty postów zawierają `id`, `content`, `author`, `created_at` i `metrics`; odpowiedzi oraz cytowane/przekazane dalej posty mogą być zagnieżdżone. Traktuj identyfikatory jako ciągi znaków.

### Limity liczby wyników

`limit` jest celem, a nie gwarancją. Bieżąca implementacja używa celu co najmniej 20: cel 20 odczytuje jedną nadrzędną stronę; większe cele automatycznie pobierają do 50 stron. Upływ czasu jest sprawdzany przed każdą stroną i nie są pobierane dalsze strony po przekroczeniu 60 sekund. Trwające żądanie do źródła nadrzędnego nadal może zająć czas, więc nie jest to ogólny limit czasu HTTP.

Zbieranie zatrzymuje się również, gdy osiągnięto cel, nadrzędne źródło nie ma następnej strony, strona jest pusta lub kursor jest brakujący. Zwrócenie mniejszej liczby niż `limit` postów nie oznacza, że żądanie się nie powiodło lub że każdy pasujący post został pobrany. Sprawdź `has_next` i `next_cursor` przed kontynuacją.

```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. Odczytaj odpowiedzi

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

| Pole | Typ | Wymagane | Znaczenie |
|---|---|---|---|
| `tweet_ids` | string or string array | Tak | Jedno ID posta lub partia do 20 ID |
| `cursor` | string | Nie | Do 4 000 znaków; używaj z jednym ID posta |
| `since_time` | integer | Nie | Czas początkowy w sekundach Unix |
| `until_time` | integer | Nie | Czas końcowy w sekundach Unix |

Zastąp symbol zastępczy rzeczywistym ID posta:

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

W przeciwieństwie do osi czasu i wyszukiwania postów, odpowiedzi są grupowane pod `results`. Każdy wpis ma własny stan stronicowania:

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

### Limity odpowiedzi na żądanie

Każde żądanie odczytuje jedną nadrzędną stronę odpowiedzi na każde `tweet_id` i zachowuje najwyżej 100 odpowiedzi; nie pobiera automatycznie każdej strony odpowiedzi. W partii do 20 ID limit 100 odpowiedzi obowiązuje osobno dla każdego wpisu `results`. Rzeczywiste liczby mogą być niższe.

`total` każdego wpisu to liczba odpowiedzi zwróconych w tym wpisie, a nie pełna liczba odpowiedzi na post. Aby kontynuować, użyj `next_cursor` tego wpisu i w następnym żądaniu wyślij tylko jego pojedyncze ID posta. Nie ma parametru `limit`, który zwiększałby limit na żądanie.

## Stronicowanie i kontrola kosztów

`total` zlicza odpowiednią tablicę w bieżącej odpowiedzi: posty najwyższego poziomu dla zapytań o posty albo odpowiedzi w każdym wpisie wyniku dla zapytań o odpowiedzi. Nie jest to globalna liczba dopasowań, pełna liczba odpowiedzi posta ani końcowa liczba rozliczeniowa.

1. Wyślij pierwsze żądanie bez `cursor`.
2. Odczytaj `has_next` i `next_cursor` z odpowiedzi. W przypadku odpowiedzi odczytuj je w każdym wpisie wyniku.
3. Jeśli istnieje kolejna strona, a kursor nie jest pusty, wyślij go bez zmian z tym samym zapytaniem. W przypadku partii odpowiedzi kontynuuj każdy post osobno.
4. Zatrzymaj się, gdy nie ma następnej strony, gdy kursor się powtarza lub gdy osiągnięto własny limit strony albo wydatków.

Metadane stronicowania odzwierciedlają ostatnią odpowiedź nadrzędną; zwrócony zbiór może zostać obcięty przez limit wyników. Nawet `has_next=false` nie gwarantuje, że cała historia X lub wszystkie odpowiedzi zostały pobrane. Wyświetlaj rzeczywistą liczbę zwróconych elementów zamiast oznaczać ograniczony zbiór jako wszystkie dostępne dane.

Każda udana strona może generować opłatę. Te pięć operacji jest rozliczanych według zwróconych wyników, a nie według stałej opłaty za żądanie. Zagnieżdżone odpowiedzi i inne zwrócone rekordy mogą wpływać na liczbę rozliczanych wyników; nie szacuj kosztu wyłącznie na podstawie długości tablicy najwyższego poziomu. Sprawdź [bieżące ceny](https://openapi.felo.ai/api/v1/data/prices) i użycie w konsoli. Pełne pola obiektów znajdują się w [schemacie OpenAPI](https://openapi.felo.ai/api/v1/data/openapi.json).