# Data X

Získejte profily X, vyhledávejte uživatele a příspěvky a stránkujte časové osy a odpovědi.

Zvolte operaci pro data, která potřebujete. Všech pět koncových bodů používá POST a vrací JSON v kořeni, bez společného obalu `data`.

Všechny příklady používají `FELO_API_KEY` z [přehledu](https://openapi.felo.ai/cs/docs/data-api/guides/felo-overview.md). Volání používají **zůstatek platformy**, nikoli Felo Pro credits. Příklady odpovědí jsou ilustrativní; živý obsah a volitelná pole se liší.

## Zvolte operaci

| Potřebuji | Konečný bod |
|---|---|
| Profily známých uživatelských jmen | `POST /api/v1/data/x/user/info` |
| Najít uživatele podle vyhledávacího dotazu | `POST /api/v1/data/x/user/search` |
| Příspěvky od jednoho uživatele | `POST /api/v1/data/x/user/tweets` |
| Příspěvky odpovídající dotazu | `POST /api/v1/data/x/tweet/search` |
| Odpovědi na známé příspěvky | `POST /api/v1/data/x/tweet/replies` |

## 1. Získejte profily uživatelů

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

| Pole | Typ | Povinné | Význam |
|---|---|---|---|
| `usernames` | pole stringů | Ano | 1–100 uživatelských jmen; posílejte handly 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"]}'
```

Odpověď obsahuje `users` a `total`. Každý uživatel zahrnuje `user_id`, `username` a `display_name`; může být přítomen také text profilu, počty sledujících, ověření a další metadata. Dávka může vrátit méně profilů, než bylo požadováno. Porovnávejte podle uživatelského jména nebo ID, nikoli podle pozice v poli.

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

## 2. Vyhledávání uživatelů

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

| Pole | Typ | Povinné | Význam |
|---|---|---|---|
| `query` | string | Ano | 1–1 000 znaků |
| `cursor` | string | Ne | Stránkovací kurzor, až 4 000 znaků |

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

Odpověď obsahuje `users`, `total`, `has_next` a `next_cursor`. Tato operace nemá parametr `limit`.

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

## 3. Získejte časovou osu uživatele

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

| Pole | Typ | Povinné | Význam |
|---|---|---|---|
| `username` | string | Vyžadován jeden identifikátor | Uživatelské jméno, až 100 znaků |
| `x_user_id` | string | Vyžadován jeden identifikátor | ID uživatele, až 100 znaků; má přednost před `username` |
| `limit` | integer | Ne | 1–1 000; současná implementace používá alespoň 20, výchozí 20 |
| `cursor` | string | Ne | Stránkovací kurzor, až 4 000 znaků |
| `include_replies` | boolean | Ne | Zahrnout zanořené odpovědi; výchozí `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}'
```

Odpověď obsahuje `tweets`, `total`, `has_next` a `next_cursor`. Nastavení `limit` pod 20 nezaručuje menší počet vrácených položek ani nižší účtování. Zahrnutí odpovědí může přidat vrácená data a zpoplatněné výsledky.

### Limity výsledků a zanořených odpovědí

`limit` je cílový počet příspěvků na nejvyšší úrovni pro tento požadavek, nikoli zaručený počet výsledků. Současná implementace používá cíl alespoň 20: cíl 20 načte jednu upstream stránku; větší cíle automaticky načtou až 50 stránek. Před každou stránkou se kontroluje uplynulý čas a další stránky se přestanou načítat, jakmile překročí 60 sekund. Tato kontrola nezaručuje, že celý HTTP požadavek skončí do 60 sekund.

Sběr se také zastaví, když je dosaženo cíle, upstream nemá další stránku, stránka je prázdná nebo chybí cursor. Úspěšná odpověď proto může obsahovat méně než `limit` příspěvků. Chcete-li pokračovat, použijte `has_next` a `next_cursor`, pokud jsou k dispozici.

S `include_replies=true` získá každý vrácený příspěvek až 5 dalších stránek a nejvýše 100 zanořených odpovědí. Sběr se může zastavit dříve, pokud není další stránka, stránka je prázdná nebo cursor nelze posunout. Tyto zanořené odpovědi jsou mimo vrchní `limit` a `total`, ale mohou přidat zpoplatněné výsledky.

Zanořené `replies` nejsou úplným archivem odpovědí a neodhalují samostatný pokračovací cursor pro tento další sběr. Chcete-li stránkovat odpovědi samostatně, použijte operaci Číst odpovědi a její vrácený cursor. Nepoužívejte cursor z vrchní úrovně příspěvku pro odpovědi znovu.

## 4. Vyhledávání příspěvků

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

| Pole | Typ | Povinné | Význam |
|---|---|---|---|
| `query` | string | Ano | Vyhledávací text, 1–1 000 znaků |
| `query_type` | string | Ne | `Latest` (výchozí) nebo `Top` |
| `limit` | integer | Ne | 1–1 000; současná implementace používá alespoň 20, výchozí 20 |
| `cursor` | string | Ne | Stránkovací kurzor, až 4 000 znaků |
| `since_time` | integer or string | Ne | Začátek; pro jednoznačnou číselnou hodnotu použijte Unix sekundy |
| `until_time` | integer or string | Ne | Konec; použijte Unix sekundy, nikoli milisekundy |

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

Odpověď obsahuje `tweets`, `total`, `has_next` a `next_cursor`. Objekty příspěvků zahrnují `id`, `content`, `author`, `created_at` a `metrics`; odpovědi a citované/retweetované příspěvky mohou být zanořené. Považujte ID za řetězce.

### Limity počtu výsledků

`limit` je cíl, nikoli záruka. Současná implementace používá cíl alespoň 20: cíl 20 načte jednu upstream stránku; větší cíle automaticky načtou až 50 stránek. Před každou stránkou se kontroluje uplynulý čas a jakmile překročí 60 sekund, žádné další stránky se nenačítají. Právě probíhající upstream požadavek může stále trvat, takže to není celkový HTTP timeout.

Sběr se také zastaví, když je dosaženo cíle, upstream nemá další stránku, stránka je prázdná nebo chybí cursor. Pokud vrátíte méně než `limit` příspěvků, neznamená to, že požadavek selhal nebo že byl načten každý odpovídající příspěvek. Před pokračováním zkontrolujte `has_next` a `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. Číst odpovědi

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

| Pole | Typ | Povinné | Význam |
|---|---|---|---|
| `tweet_ids` | string nebo pole stringů | Ano | Jedno ID příspěvku nebo dávka až 20 ID |
| `cursor` | string | Ne | Až 4 000 znaků; použijte s jedním ID příspěvku |
| `since_time` | integer | Ne | Začátek v Unix sekundách |
| `until_time` | integer | Ne | Konec v Unix sekundách |

Nahraďte zástupný symbol skutečným ID příspěvku:

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

Na rozdíl od časové osy a vyhledávání příspěvků jsou odpovědi seskupeny pod `results`. Každá položka má vlastní stav stránkování:

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

### Limity odpovědí na jeden požadavek

Každý požadavek načte jednu upstream stránku odpovědí pro každý `tweet_id` a ponechá nejvýše 100 odpovědí; neprochází automaticky každou stránku odpovědí. V dávce až 20 ID platí limit 100 odpovědí samostatně pro každou položku `results`. Skutečné počty mohou být nižší.

`total` každé položky je počet odpovědí vrácených v této položce, nikoli úplný počet odpovědí na příspěvek. Chcete-li pokračovat, použijte `next_cursor` dané položky a v dalším požadavku odešlete pouze její jedno ID příspěvku. Pro zvýšení per-request limitu neexistuje parametr `limit`.

## Stránkování a řízení nákladů

`total` počítá odpovídající pole v aktuální odpovědi: příspěvky na nejvyšší úrovni pro dotazy na příspěvky nebo odpovědi uvnitř každé položky výsledku pro dotazy na odpovědi. Není to globální počet shod, úplný počet odpovědí na příspěvek ani konečný zpoplatněný počet.

1. Odešlete první požadavek bez `cursor`.
2. Přečtěte `has_next` a `next_cursor` z odpovědi. U odpovědí je čtěte v každé položce výsledku.
3. Pokud existuje další stránka a cursor není prázdný, odešlete jej beze změny se stejným dotazem. U dávky odpovědí pokračujte u každého příspěvku samostatně.
4. Zastavte se, když není další stránka, když se cursor opakuje nebo když je dosažen váš vlastní limit stránek či utrácení.

Metadata stránkování odrážejí poslední upstream odpověď; vrácený soubor může být zkrácen na limit výsledků. Ani `has_next=false` není zárukou, že byla načtena veškerá historie X nebo všechny odpovědi. Zobrazte skutečný vrácený počet místo označení omezené sady výsledků jako všech dostupných dat.

Každá úspěšná stránka může být zpoplatněna. Těchto pět operací je účtováno podle vrácených výsledků, nikoli paušálním poplatkem za požadavek. Zanořené odpovědi a další vrácené záznamy mohou ovlivnit zpoplatněný počet; náklady neodhadujte pouze podle délky pole na nejvyšší úrovni. Zkontrolujte [aktuální ceny](https://openapi.felo.ai/api/v1/data/prices) a využití v konzoli. Úplná pole objektů jsou ve [schématu OpenAPI](https://openapi.felo.ai/api/v1/data/openapi.json).