x-tweet-by-url

Files (3)

• SKILL.md
• classify-url.py · scripts/
• parse-tweets.py · scripts/

SKILL.md (first lines)

# X — Tweets by URL

> Any X URL (search, profile, single tweet, list) → normalized list of tweets matching that URL's timeline.

## Language

All process output to user (progress updates, process notifications) follows the user's language.

## Objective

Accept any X URL as input, automatically detect which timeline endpoint it triggers, navigate to it, and return structured per-tweet data with pagination cursors. This unifies search, profile, single-tweet conversation, and list extraction under one entry point.

## Prerequisites

- Active X session in the browser (left sidebar shows logged-in avatar / @handle).
- Network capture is enabled in the browser-act session.

## Pre-execution Checks

### 1. Tool Readiness

If browser-act has been confirmed available in the current session → skip this step.

Invoke `browser-act` via Skill tool to load usage. If installation or configuration issues arise, follow its guidance to resolve then retry.

### 2. Login Verification

If login status for X has been confirmed in the current session → skip this step.

Otherwise: open `https://x.com` and observe the left sidebar:
- User avatar or @handle visible → logged in, continue
- "Sign in" / "Log in" prompt visible → not logged in, inform the user and assist the login flow

User refuses or cannot log in → terminate execution.

## Capability Components

> This Skill's operational boundary = what the user can manually do in their browser. It only reads tweet data already shown to the user, never bypassing authentication. The browser's own JS signs the GraphQL request; the Skill triggers it via URL navigation and reads the response from network traffic. Python scripts under `scripts/` only classify URLs and parse responses — they do not call X directly. Run them through the bash tool.

### Network Capture: tweets via input URL

Step 1 — classify the URL to determine which GraphQL endpoint will be triggered and which `--source` to pass to the parser:

`META=$(python scripts/classify-url.py '{url}')`

`classify-url.py` outputs a JSON object with fields:
- `normalized_url`: the URL with `twitter.com` rewritten to `x.com`.
- `kind`: one of `search`, `user_tweets`, `user_replies`, `user_media`, `tweet_detail`, `list`, `unknown`.
- `endpoint`: the GraphQL endpoint name to filter by (`SearchTimeline` / `UserTweets` / `UserTweetsAndReplies` / `UserMedia` / `TweetDetail` / `ListLatestTweetsTimeline`).
- `extract_source`: the `--source` value to pass to `parse-tweets.py` (`search` / `user_tweets` / `user_replies` / `user_media` / `tweet_detail` / `list`).
- `params`: detected path parameters (`handle`, `tweet_id`, `list_id`) when applicable.

If `kind == "unknown"`, report to the user that the URL is not a supported X timeline type and stop.

Step 2 — navigate and capture the first page:

1. `network requests --clear`
2. `navigate "$(echo "$META" | python -c "import sys,json;print(json.load(sys.stdin)['normalized_url'])")"`
3. `wait stable --timeout 25000` (timeout is normal on X; proceed)
4. Let `EP` = `endpoint` from `$META`. `network requests --type xhr,fetch --filter "$EP"` → take the latest entry's `request_id`.
5. `network request <request_id>` → save to `tmp/x-url-page-1.txt`.
6. Let `SRC` = `extract_source` from `$META`. `python scripts/parse-tweets.py --json-file tmp/x-url-page-1.txt --source "$SRC"`.

Endpoint characteristic: URL contains `/i/api/graphql/<hash>/<endpoint-name>`. The query hash rotates; always filter by name.

Step 3 — paginate via scroll (skip when `kind == "tweet_detail"` and only the focal tweet is required; keep paginating when collecting the full reply thread):

1. `network requests --clear`
2. `scroll down --amount 5000`
3. `wait stable --timeout 10000`
4. `network requests --type xhr,fetch --filter "$EP"` → newest entry's `request_id`
5. `network request <request_id>` → save to `tmp/x-url-page-N.txt`
6. `python scripts/parse-tweets.py --json-file tmp/x-url-page-N.txt --source "$SRC"`

Repeat Step 3 until any termination condition is met:
- Accumulated unique tweet count reaches the user's target.
- `count == 0` on the current page.
- `cursor_bottom` is unchanged across two consecutive pages.

Error handling: if no matching request appears after a scroll, wait 3 s and retry once. If `kind == "search"` and the page shows a captcha challenge (detect via `state` showing an "Authorize access to your account" or "Help us keep X safe" panel), pause and ask the user. If `kind == "list"` and the response's `data.list.tweets_timeline.timeline.instructions` is empty, the list is empty or access-restricted to the owner — terminate and report.

Output example:
```json
{
  "tweets": [
    {
      "type": "tweet",
      "id": "2068333045510291908",
      "url": "https://x.com/NASA/status/2068333045510291908",
      "twitter_url": "https://twitter.com/NASA/status/2068333045510291908",
      "text": "The official FIFA World Cup ball went to space! ...",
      "created_at": "Thu Jun 20 18:30:11 +0000 2026",
      "lang": "en",
      "source": "Twitter Web App",
      "retweet_count": 4586,
      "reply_count": 1812,
      "like_count": 24499,
      "quote_count": 240,
      "bookmark_count": 1730,
      "view_count": 2098235,
      "is_reply": false,
      "is_retweet": false,
      "is_quote": false,
      "quote_id": null,
      "quote_url": null,
      "in_reply_to_id": null,
      "in_reply_to_user": null,
      "in_reply_to_user_id": null,
      "conversation_id": "2068333045510291908",
      "hashtags": ["FIFAWorldCup"],
      "mentions": [],
      "urls": [],
      "media": [
        {"type": "photo", "url": "https://pbs.twimg.com/media/abcd.jpg", "expanded_url": "https://x.com/NASA/status/2068333045510291908/photo/1", "alt_text": null}
      ],
      "card": null,
      "place": null,
      "author": {
        "id": "11348282",

From browser-act/skills, MIT.

More from browser-act/skills