# readx API Reference

## API Call Pattern

```
GET https://readx.cc/consumer/{Endpoint}?api_key={API_KEY}&param1=value1&param2=value2
```

All requests are GET with query parameters. Responses are JSON.

---

## Endpoints

### Users

| Endpoint | Params | Description |
|----------|--------|-------------|
| `UserResultByScreenName` | `username` | Get user profile by username |
| `UserResultByRestId` | `user_id` | Get user profile by ID |
| `UsernameToUserId` | `username` | Convert username to user_id |
| `FollowersLight` | `username`, `count?` | Get followers list |
| `FollowingLight` | `username`, `count?` | Get following list |
| `FollowingIds` | `username`, `count?`, `stringify_ids=true` | Get following IDs only |
| `UserVerifiedFollowers` | `user_id`, `cursor?` | Get verified followers |
| `FriendshipsShow` | `source_screen_name`, `target_screen_name` | Check relationship between two users |

### Tweets

| Endpoint | Params | Description |
|----------|--------|-------------|
| `UserTweets` | `user_id`, `cursor?` | Get user's tweets |
| `UserTweetsReplies` | `user_id`, `cursor?` | Get user's tweets and replies |
| `UserMedia` | `user_id`, `cursor?` | Get user's media posts |
| `TweetDetail` | `tweet_id` | Get tweet detail (minimal) |
| `TweetDetailv2` | `tweet_id` | Get tweet detail (preferred, includes views/source) |
| `TweetDetailv3` | `tweet_id` | Get tweet detail (includes view_count) |
| `TweetDetailConversation` | `tweet_id` | Get tweet with conversation thread |
| `TweetDetailConversationv2` | `tweet_id`, `cursor?` | Get tweet with full reply thread (preferred) |
| `TweetResultsByRestIds` | `tweet_ids` (comma-separated) | Batch get tweets |
| `TweetFavoriters` | `tweet_id`, `cursor?` | Get users who liked a tweet |
| `TweetRetweeters` | `tweet_id`, `cursor?` | Get users who retweeted |
| `TweetQuotes` | `tweet_id`, `cursor?` | Get quote tweets |
| `TweetArticle` | `tweet_id` | Get long-form article content |

### Search

| Endpoint | Params | Description |
|----------|--------|-------------|
| `Search` | `q`, `count?`, `type?` (Top/Latest), `cursor?`, `safe_search?` | Search tweets |
| `AutoComplete` | `q` | Search autocomplete suggestions |

### Lists

| Endpoint | Params | Description |
|----------|--------|-------------|
| `ListTweetsTimeline` | `list_id`, `cursor?` | Get tweets from a list |
| `ListSubscribersTimeline` | `list_id`, `cursor?` | Get list subscribers |
| `ListMembersTimeline` | `list_id`, `cursor?` | Get list members |
| `ListSearch` | `q` | Search for lists |

### Communities

| Endpoint | Params | Description |
|----------|--------|-------------|
| `CommunityResultsById` | `community_id` | Get community details |
| `CommunitiesSearchSlice` | `q` | Search communities |
| `CommunityTimeline` | `community_id`, `type?` (Relevance/Recency), `time_filter?` (Day/Week/Month), `cursor?` | Get community tweets |
| `CommunityAboutTimeline` | `community_id`, `cursor?` | Get community media |
| `CommunityMembers` | `community_id` | Get community members |
| `CommunityModerators` | `community_id` | Get community moderators |
| `CommunityMemberSearch` | `community_id`, `q` | Search community members |

### Trends

| Endpoint | Params | Description |
|----------|--------|-------------|
| `Trends` | `woeid` | Get trending topics for a location |

Common WOEID values: 1 (Worldwide), 23424977 (US), 23424975 (UK), 23424856 (Japan), 23424868 (South Korea), 23424781 (Germany), 23424819 (France), 23424748 (Australia), 23424829 (India), 23424900 (Mexico), 23424950 (Singapore), 23424948 (Saudi Arabia), 23424787 (Brazil).

### Account

| Endpoint | Params | Description |
|----------|--------|-------------|
| `CreditBalance` | (none) | Get remaining API credits. Each call costs 1 credit. |

---

## Response Parsing

API responses use deeply nested Twitter JSON. Key extraction paths:

### User profile

Response from `UserResultByScreenName`:

```
data.user_results.result → {
  rest_id,
  core.name, core.screen_name, core.created_at,
  profile_bio.description,
  location.location,
  avatar.image_url,
  relationship_counts.followers, relationship_counts.following,
  tweet_counts.tweets,
  verification.is_blue_verified, verification.verified_type,
  website.url,
  privacy.protected
}
```

### Tweet

For `TweetDetail`: look in `data.tweet_result`
For `TweetDetailv2`: look in `data.tweetResult`
For `TweetDetailv3`: look in `data.tweet_results`

Note: some tweets are wrapped in `TweetWithVisibilityResults` — access `.tweet` inside it to get the actual tweet object.

```
.result.legacy → {
  full_text, favorite_count, retweet_count, reply_count,
  quote_count, bookmark_count, created_at
}
.result.core.user_results.result → author info (rest_id, core.name, core.screen_name)
.result.legacy.extended_entities.media → media attachments (type, media_url_https, video_info)
```

Views (v2): `.result.views.count`
Views (v3): `.result.view_count_info.count`

### Timeline (tweets/users lists)

Responses contain an `instructions[]` array:

```
instructions[].entries[].content.itemContent.tweet_results → individual tweets
instructions[].entries[].content.items[].item.itemContent.tweet_results → conversation module tweets
```

Pinned tweets appear in instructions with `__typename: "TimelinePinEntry"`.

### Pagination

Look for cursor entries in instructions:

```
instructions[].entries[].content → where cursor_type = "Bottom" → .value = next_cursor
```

Pass this value as the `cursor` parameter to get the next page.

### Trends

Response from `Trends`:

```
metadata.woeid.name → location name
modules[].trend → { name, rank, target.query }
```

### Credit balance

Response from `CreditBalance`:

```
{ credits: <number> }
```

---

## Examples

```bash
# Get user profile
curl -s "https://readx.cc/consumer/UserResultByScreenName?api_key=${READX_API_KEY}&username=elonmusk" \
  | jq '.data.user_results.result | {id: .rest_id, name: .core.name, username: .core.screen_name, followers: .relationship_counts.followers}'

# Search tweets
curl -s "https://readx.cc/consumer/Search?api_key=${READX_API_KEY}&q=AI&count=20&type=Top"

# Get user tweets (need user_id first)
curl -s "https://readx.cc/consumer/UserTweets?api_key=${READX_API_KEY}&user_id=44196397"

# Check credit balance
curl -s "https://readx.cc/consumer/CreditBalance?api_key=${READX_API_KEY}"
```