# X (Twitter) — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API |
> |---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Read tweets, search posts, look up users, get timelines, followers, and trending topics from X/Twitter.

**Category:** Social Media | **Website:** [x.com](https://x.com) | **Docs:** [docs.x.com/x-api/introduction](https://docs.x.com/x-api/introduction)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/x/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### Tweet Lookup

Get a single tweet by its ID with optional field expansions.

**Estimated cost:** $0.016

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Tweet ID |
| `tweet.fields` | string | No | Comma-separated tweet fields: attachments, author_id, created_at, entities, geo, id, lang, public_metrics, source, text, etc. |
| `user.fields` | string | No | Comma-separated user fields: created_at, description, id, location, name, profile_image_url, public_metrics, username, verified, etc. |
| `expansions` | string | No | Comma-separated expansions: author_id, referenced_tweets.id, attachments.media_keys, etc. |
| `media.fields` | string | No | Comma-separated media fields: duration_ms, height, media_key, preview_image_url, type, url, width, public_metrics, etc. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/x/tweet-lookup \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"<string>","tweet.fields":"<string>","user.fields":"<string>","expansions":"<string>","media.fields":"<string>"}'
```

### Tweets Batch Lookup

Get multiple tweets by IDs in a single request (up to 100).

**Estimated cost:** $0.016

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ids` | string \| string[] | Yes | Comma-separated tweet IDs or array (max 100) |
| `tweet.fields` | string | No | Comma-separated tweet fields: attachments, author_id, created_at, entities, geo, id, lang, public_metrics, source, text, etc. |
| `user.fields` | string | No | Comma-separated user fields: created_at, description, id, location, name, profile_image_url, public_metrics, username, verified, etc. |
| `expansions` | string | No | Comma-separated expansions: author_id, referenced_tweets.id, attachments.media_keys, etc. |
| `media.fields` | string | No | Comma-separated media fields: duration_ms, height, media_key, preview_image_url, type, url, width, public_metrics, etc. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/x/tweets-lookup \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":"<string | string[]>","tweet.fields":"<string>","user.fields":"<string>","expansions":"<string>","media.fields":"<string>"}'
```

### Search Recent Tweets

Search tweets from the last 7 days using the X query language. Supports operators like from:, to:, is:retweet, has:media, etc.

**Estimated cost:** $0.016

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search query (up to 512 characters). Supports operators like from:username, has:links, is:reply, lang:en, etc. |
| `sort_order` | string | No | Sort order: 'recency' or 'relevancy' |
| `start_time` | string | No | Oldest UTC datetime (ISO 8601) |
| `end_time` | string | No | Newest UTC datetime (ISO 8601) |
| `max_results` | number | No | Maximum results to return (10-100) |
| `pagination_token` | string | No | Token for paginating through results |
| `tweet.fields` | string | No | Comma-separated tweet fields: attachments, author_id, created_at, entities, geo, id, lang, public_metrics, source, text, etc. |
| `user.fields` | string | No | Comma-separated user fields: created_at, description, id, location, name, profile_image_url, public_metrics, username, verified, etc. |
| `expansions` | string | No | Comma-separated expansions: author_id, referenced_tweets.id, attachments.media_keys, etc. |
| `media.fields` | string | No | Comma-separated media fields: duration_ms, height, media_key, preview_image_url, type, url, width, public_metrics, etc. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/x/tweet-search-recent \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>","sort_order":"<string>","start_time":"<string>","end_time":"<string>","max_results":"<number>","pagination_token":"<string>","tweet.fields":"<string>","user.fields":"<string>","expansions":"<string>","media.fields":"<string>"}'
```

### Recent Tweet Counts

Get the count of tweets matching a query over the last 7 days, bucketed by time granularity.

**Estimated cost:** $0.016

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search query (same syntax as search endpoint) |
| `granularity` | string | No | Time bucket size: 'minute', 'hour', or 'day' (default: hour) |
| `start_time` | string | No | Oldest UTC datetime (ISO 8601) |
| `end_time` | string | No | Newest UTC datetime (ISO 8601) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/x/tweet-count-recent \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>","granularity":"<string>","start_time":"<string>","end_time":"<string>"}'
```

### Quote Tweets

Get tweets that quote a specific tweet.

**Estimated cost:** $0.016

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Tweet ID to find quotes of |
| `max_results` | number | No | Maximum results to return (10-100) |
| `pagination_token` | string | No | Token for paginating through results |
| `tweet.fields` | string | No | Comma-separated tweet fields: attachments, author_id, created_at, entities, geo, id, lang, public_metrics, source, text, etc. |
| `user.fields` | string | No | Comma-separated user fields: created_at, description, id, location, name, profile_image_url, public_metrics, username, verified, etc. |
| `expansions` | string | No | Comma-separated expansions: author_id, referenced_tweets.id, attachments.media_keys, etc. |
| `media.fields` | string | No | Comma-separated media fields: duration_ms, height, media_key, preview_image_url, type, url, width, public_metrics, etc. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/x/tweet-quotes \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"<string>","max_results":"<number>","pagination_token":"<string>","tweet.fields":"<string>","user.fields":"<string>","expansions":"<string>","media.fields":"<string>"}'
```

### Liking Users

Get users who liked a specific tweet.

**Estimated cost:** $0.016

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Tweet ID |
| `max_results` | number | No | Maximum results to return (10-100) |
| `pagination_token` | string | No | Token for paginating through results |
| `user.fields` | string | No | Comma-separated user fields to include |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/x/tweet-liking-users \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"<string>","max_results":"<number>","pagination_token":"<string>","user.fields":"<string>"}'
```

### Retweeted By

Get users who retweeted a specific tweet.

**Estimated cost:** $0.016

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Tweet ID |
| `max_results` | number | No | Maximum results to return (10-100) |
| `pagination_token` | string | No | Token for paginating through results |
| `user.fields` | string | No | Comma-separated user fields to include |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/x/tweet-retweeted-by \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"<string>","max_results":"<number>","pagination_token":"<string>","user.fields":"<string>"}'
```

### User Lookup

Get a single user by their ID.

**Estimated cost:** $0.016

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | User ID |
| `tweet.fields` | string | No | Comma-separated tweet fields: attachments, author_id, created_at, entities, geo, id, lang, public_metrics, source, text, etc. |
| `user.fields` | string | No | Comma-separated user fields: created_at, description, id, location, name, profile_image_url, public_metrics, username, verified, etc. |
| `expansions` | string | No | Comma-separated expansions: author_id, referenced_tweets.id, attachments.media_keys, etc. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/x/user-lookup \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"<string>","tweet.fields":"<string>","user.fields":"<string>","expansions":"<string>"}'
```

### Users Batch Lookup

Get multiple users by IDs in a single request (up to 100).

**Estimated cost:** $0.016

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ids` | string \| string[] | Yes | Comma-separated user IDs or array (max 100) |
| `tweet.fields` | string | No | Comma-separated tweet fields: attachments, author_id, created_at, entities, geo, id, lang, public_metrics, source, text, etc. |
| `user.fields` | string | No | Comma-separated user fields: created_at, description, id, location, name, profile_image_url, public_metrics, username, verified, etc. |
| `expansions` | string | No | Comma-separated expansions: author_id, referenced_tweets.id, attachments.media_keys, etc. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/x/users-lookup \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":"<string | string[]>","tweet.fields":"<string>","user.fields":"<string>","expansions":"<string>"}'
```

### User by Username

Get a user by their @username.

**Estimated cost:** $0.016

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `username` | string | Yes | Username (without @ prefix) |
| `tweet.fields` | string | No | Comma-separated tweet fields: attachments, author_id, created_at, entities, geo, id, lang, public_metrics, source, text, etc. |
| `user.fields` | string | No | Comma-separated user fields: created_at, description, id, location, name, profile_image_url, public_metrics, username, verified, etc. |
| `expansions` | string | No | Comma-separated expansions: author_id, referenced_tweets.id, attachments.media_keys, etc. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/x/user-by-username \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"<string>","tweet.fields":"<string>","user.fields":"<string>","expansions":"<string>"}'
```

### Users by Usernames

Get multiple users by their @usernames in a single request (up to 100).

**Estimated cost:** $0.016

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `usernames` | string \| string[] | Yes | Comma-separated usernames or array (max 100) |
| `tweet.fields` | string | No | Comma-separated tweet fields: attachments, author_id, created_at, entities, geo, id, lang, public_metrics, source, text, etc. |
| `user.fields` | string | No | Comma-separated user fields: created_at, description, id, location, name, profile_image_url, public_metrics, username, verified, etc. |
| `expansions` | string | No | Comma-separated expansions: author_id, referenced_tweets.id, attachments.media_keys, etc. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/x/users-by-usernames \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":"<string | string[]>","tweet.fields":"<string>","user.fields":"<string>","expansions":"<string>"}'
```

### User Tweets

Get a user's authored tweets (up to 3,200 most recent).

**Estimated cost:** $0.016

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | User ID |
| `exclude` | string | No | Comma-separated: 'retweets', 'replies' |
| `max_results` | number | No | Maximum results to return (10-100) |
| `pagination_token` | string | No | Token for paginating through results |
| `tweet.fields` | string | No | Comma-separated tweet fields: attachments, author_id, created_at, entities, geo, id, lang, public_metrics, source, text, etc. |
| `user.fields` | string | No | Comma-separated user fields: created_at, description, id, location, name, profile_image_url, public_metrics, username, verified, etc. |
| `expansions` | string | No | Comma-separated expansions: author_id, referenced_tweets.id, attachments.media_keys, etc. |
| `media.fields` | string | No | Comma-separated media fields: duration_ms, height, media_key, preview_image_url, type, url, width, public_metrics, etc. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/x/user-tweets \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"<string>","exclude":"<string>","max_results":"<number>","pagination_token":"<string>","tweet.fields":"<string>","user.fields":"<string>","expansions":"<string>","media.fields":"<string>"}'
```

### User Mentions

Get tweets that mention a specific user (up to 800 most recent).

**Estimated cost:** $0.016

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | User ID |
| `max_results` | number | No | Maximum results to return (10-100) |
| `pagination_token` | string | No | Token for paginating through results |
| `tweet.fields` | string | No | Comma-separated tweet fields: attachments, author_id, created_at, entities, geo, id, lang, public_metrics, source, text, etc. |
| `user.fields` | string | No | Comma-separated user fields: created_at, description, id, location, name, profile_image_url, public_metrics, username, verified, etc. |
| `expansions` | string | No | Comma-separated expansions: author_id, referenced_tweets.id, attachments.media_keys, etc. |
| `media.fields` | string | No | Comma-separated media fields: duration_ms, height, media_key, preview_image_url, type, url, width, public_metrics, etc. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/x/user-mentions \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"<string>","max_results":"<number>","pagination_token":"<string>","tweet.fields":"<string>","user.fields":"<string>","expansions":"<string>","media.fields":"<string>"}'
```

### User Followers

Get a user's followers.

**Estimated cost:** $0.016

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | User ID |
| `max_results` | number | No | Maximum results to return (10-100) |
| `pagination_token` | string | No | Token for paginating through results |
| `user.fields` | string | No | Comma-separated user fields to include |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/x/user-followers \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"<string>","max_results":"<number>","pagination_token":"<string>","user.fields":"<string>"}'
```

### User Following

Get users that a specific user follows.

**Estimated cost:** $0.016

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | User ID |
| `max_results` | number | No | Maximum results to return (10-100) |
| `pagination_token` | string | No | Token for paginating through results |
| `user.fields` | string | No | Comma-separated user fields to include |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/x/user-following \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"<string>","max_results":"<number>","pagination_token":"<string>","user.fields":"<string>"}'
```

### Trending Topics

Get trending topics for a location by WOEID (Where On Earth ID). Common WOEIDs: 1 (Worldwide), 23424977 (US), 23424975 (UK), 23424856 (Japan).

**Estimated cost:** $0.016

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `woeid` | number | Yes | Where On Earth ID — 1 for worldwide, 23424977 for US, etc. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/x/trends \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"woeid":"<number>"}'
```