x-read

Files (5)

• SKILL.md
• auth-setup.md · references/
• endpoints.md · references/
• migration-to-apify.md · references/
• x-read.sh · scripts/

SKILL.md (first lines)

# x-read — Read tweets via X API v2

Read-only client for the X (Twitter) v2 API. V1 wraps the eight most useful read endpoints behind a single bash script so any agent can paste a URL and get the tweet, fetch a user's timeline, check mentions, dump bookmarks, or run a recent-search.

Posting, liking, following, and quote-posting are intentionally out of scope — those endpoints were removed from self-serve in April 2026 and require enterprise tier. Posting via API is also $0.20/post which is not worth it.

## When to invoke

Trigger this skill when the user:

- Pastes an `x.com/<user>/status/<id>` or `twitter.com/...` URL and wants the contents.
- Asks "what's in this tweet", "summarize this thread", "what did X say".
- Asks for their own mentions, bookmarks, liked tweets, or recent posts.
- Asks "what's a user tweeting about lately" or "show me <user>'s timeline".
- Asks for a recent-search ("tweets about <topic> from this week").

Skip and use the browser/headless path only if the user explicitly wants screenshots, the tweet is age-gated, or the API returns 403 (protected account).

## Prerequisites — secrets the operator must set

Set in the gateway environment (per OpenClaw env conventions):

| Variable | Required for | How to get it |
| --- | --- | --- |
| `X_BEARER_TOKEN` | All public reads (tweet by id, timelines, mentions, search) | https://developer.x.com — Project → App → "Bearer Token". Pay-per-use plan, no flat tier. |
| `X_USER_OAUTH_TOKEN` | Owned reads that need user context (bookmarks, liked_tweets when private) | OAuth 2.0 PKCE user token with `bookmark.read tweet.read users.read like.read` scopes. |
| `X_USER_ID` | Convenience — let the user say "my mentions" without re-typing the numeric id | `curl -H "Authorization: Bearer $X_USER_OAUTH_TOKEN" https://api.x.com/2/users/me \| jq -r .data.id` |

If any required token is missing, the script exits with code `2` and a clear `missing X_BEARER_TOKEN` message. Do NOT fall back to scraping or guessing — surface the missing-secret error to the user verbatim and stop.

## Cost model (as of 2026-04-20)

| Endpoint | Per call | Notes |
| --- | --- | --- |
| `GET /2/tweets/{id}` (someone else's) | $0.005 | "Read" billing tier |
| `GET /2/users/{me}/tweets` (own timeline) | $0.001 | "Owned read" tier — 5× cheaper |
| `GET /2/users/{me}/mentions` | $0.001 | Owned read |
| `GET /2/users/{me}/bookmarks` | $0.001 | Owned read; needs OAuth user token |
| `GET /2/users/{me}/liked_tweets` | $0.001 | Owned read |
| `GET /2/tweets/search/recent` | $0.005 | 7-day window only; use Apify for historical |

Hard cap: 2,000,000 post-reads/month before Enterprise tier. The script does NOT auto-batch or auto-paginate beyond `max_results` (default 10) — the agent must explicitly request more.

## Usage

The skill ships a single bash entrypoint: `scripts/x-read.sh`. All commands print JSON (`--pretty` for indented). Pipe through `jq` for shaping.

```bash
# Single tweet (URL or id)
./scripts/x-read.sh tweet https://x.com/elonmusk/status/1234567890
./scripts/x-read.sh tweet 1234567890

# Multiple tweets in one call (cheaper)
./scripts/x-read.sh tweets 1234567890,1234567891,1234567892

# A user's recent posts
./scripts/x-read.sh timeline elonmusk          # by username
./scripts/x-read.sh timeline 44196397 --max 25 # by numeric id

# My mentions / bookmarks / likes (uses X_USER_ID)
./scripts/x-read.sh mentions
./scripts/x-read.sh bookmarks
./scripts/x-read.sh likes

# Recent search (last 7 days)
./scripts/x-read.sh search '"openclaw" -is:retweet lang:en' --max 50

# Resolve a username -> numeric id (handy + cheap)
./scripts/x-read.sh whois marcelfahle
```

Output is the raw `data`/`includes` envelope from the X API. Agents should parse `.data[].text`, `.includes.users[]`, `.includes.tweets[]` (for thread context) directly.

## Reading a thread

X v2 doesn't have a "give me this thread" endpoint. The script's `thread <id>` subcommand:

1. Fetches the leaf tweet with `expansions=referenced_tweets.id,author_id`.
2. Walks `referenced_tweets[type=replied_to]` upward until it hits a root.
3. Then fetches the author's recent posts and stitches forward replies that share `conversation_id`.

This costs ~3–6 reads for a typical thread. For deeper threads, prefer Apify (V2 plan).

## Anti-patterns (do NOT do)

1. **Never invent tweet text.** If the API returns 404 or `errors[]`, surface the error verbatim. No paraphrasing from training data.
2. **Never log the bearer token.** The script masks tokens in error output; agents must not echo `$X_BEARER_TOKEN` to the user or to logs.
3. **Don't auto-paginate past `max_results=100`.** That burns the monthly cap fast. Ask the user to confirm before fetching > 100 tweets.
4. **Don't use this for posting, liking, following, retweeting, or quote-posting.** Those endpoints aren't included on purpose.
5. **Don't fall back to scraping x.com via the browser tool when an API call fails with rate-limit (429).** Honor the rate limit and tell the user.

## Reference index

- `references/endpoints.md` — Full endpoint catalog (URL, params, fields, costs).
- `references/auth-setup.md` — Step-by-step OAuth 2.0 PKCE flow to mint the user token for bookmarks.
- `references/migration-to-apify.md` — When and how to switch this skill to the Apify "Cheap & Simple X" actor for bulk/historical (~$0.00046/tweet).

## Roadmap

- **V1 (this):** read-only, X API v2 official, bearer + optional user OAuth token.
- **V2:** Apify backend behind the same CLI surface for bulk/historical reads at ~20× cheaper per tweet.
- **V3:** thread reconstruction via Grok's free conversation expansion (when/if available on the public API).

From marcelfahle/skills, MIT.

More from marcelfahle/skills