{
  "markdown": "# fetcher-skills\n\nAgent skills for [fetcher.sh](https://fetcher.sh) — pay-per-call web-data APIs for\nTwitter/X, TikTok, Instagram, YouTube, Reddit, Google Search, Google Maps,\nGoogle News, Google Play, the App Store, and Yelp. Every call is paid in USDC,\neither per request via [x402](https://x402.org) or prepaid against a credit\nbalance with a Bearer API key. No OAuth, no signup form, no API key request\nqueue — an agent can start pulling data in one HTTP round trip.\n\nEach service is its own skill so an agent only loads the one it needs; a\nshared `fetcher` skill covers payment, credits, and MCP setup once for all of\nthem.\n\n## Why fetcher.sh\n\n- **No OAuth, no app review.** You authenticate to `fetcher.sh`'s own hosts,\n  not to Twitter/TikTok/Instagram/etc. — there's no developer-account queue\n  to wait on for any of the 11 services.\n- **Pay per call, not per tier.** $0.002–$0.005/request depending on\n  endpoint, prepaid credits or [x402](https://x402.org) micropayments in\n  USDC. No monthly minimum, no unused-tier waste.\n- **One host per service, one pattern for all of them.** `twitter.fetcher.sh`,\n  `tiktok.fetcher.sh`, `instagram.fetcher.sh`, and eight more — same\n  `{ \"status\", \"message\", \"data\" }` envelope, same auth, same MCP tool names\n  everywhere.\n- **MCP-native.** Every host exposes `/mcp` with `search_endpoints`,\n  `describe_endpoint`, `fetch_data`, and a named hero-endpoint shortcut, so an\n  MCP-connected agent can explore and call the API without reading a spec\n  first.\n- **Machine-readable everywhere.** `/openapi.json`, `/llms.txt`, and\n  `/skill.md` are generated from the live route handlers on every host, so\n  they can't drift out of sync with what actually ships.\n\n## What you can fetch\n\n| Service | Skill | Base URL | What it covers |\n| --- | --- | --- | --- |\n| Twitter / X | [`twitter-api`](skills/twitter-api/SKILL.md) / [`x-api`](skills/x-api/SKILL.md) | `twitter.fetcher.sh` | Search tweets, resolve profiles by handle or ID, and pull timelines, replies, followers, lists, and trends |\n| TikTok | [`tiktok-api`](skills/tiktok-api/SKILL.md) | `tiktok.fetcher.sh` | Search posts, resolve users by handle, and pull followers, hashtags, music, comments, and replies |\n| Instagram | [`instagram-api`](skills/instagram-api/SKILL.md) | `instagram.fetcher.sh` | Profiles, posts, reels, stories, followers, hashtags, locations, and comment threads |\n| YouTube | [`youtube-api`](skills/youtube-api/SKILL.md) | `youtube.fetcher.sh` | Search videos, channels, and playlists; fetch video details, comments, shorts, live streams, and trending |\n| Reddit | [`reddit-api`](skills/reddit-api/SKILL.md) | `reddit.fetcher.sh` | Search posts, subreddits, and users; pull hot/new/top/best feeds, comment trees, and user history |\n| Google Search | [`google-search`](skills/google-search/SKILL.md) | `google.fetcher.sh` | Programmatic Google web search results as clean JSON |\n| Google Maps | [`google-maps`](skills/google-maps/SKILL.md) | `google-maps.fetcher.sh` | Place search, place details, and reviews |\n| Google News | [`google-news`](skills/google-news/SKILL.md) | `google-news.fetcher.sh` | Headlines by section (world, business, technology, ...), keyword search, topics, and article URL decoding |\n| Google Play | [`google-play`](skills/google-play/SKILL.md) | `googleplay.fetcher.sh` | App search, app details, reviews, permissions, data safety, and developer catalogs |\n| App Store | [`app-store`](skills/app-store/SKILL.md) | `appstore.fetcher.sh` | Apple App Store app and bundle lookups, reviews, similar apps, and developer catalogs |\n| Yelp | [`yelp`](skills/yelp/SKILL.md) | `yelp.fetcher.sh` | Business search by query and location, place details, and reviews |\n| Shared | [`fetcher`](skills/fetcher/SKILL.md) | `fetcher.sh` | Credits, x402, MCP, key hygiene — read this once, applies to every skill above |\n\n`twitter-api` and `x-api` point at the same host and cover the same\nendpoints under two names, so a request for either \"Twitter\" or \"X\" resolves.\n\n## Which endpoint do I need?\n\nThe fastest way in, before reading any single skill in full:\n\n| I want to... | Call | Skill |\n| --- | --- | --- |\n| Search tweets/posts by keyword or operator | `GET twitter.fetcher.sh/api/search` | [`twitter-api`](skills/twitter-api/SKILL.md) |\n| Get an X/Twitter account's followers | `GET twitter.fetcher.sh/api/user/{id}/followers` | [`twitter-api`](skills/twitter-api/SKILL.md) |\n| Find viral TikTok posts for a keyword | `GET tiktok.fetcher.sh/api/post/search?sortType=MOST_LIKED` | [`tiktok-api`](skills/tiktok-api/SKILL.md) |\n| Look up a TikTok profile by @username | `GET tiktok.fetcher.sh/api/user/handle/{username}` | [`tiktok-api`](skills/tiktok-api/SKILL.md) |\n| Look up an Instagram profile by @handle | `GET instagram.fetcher.sh/api/user/handle/{handle}` | [`instagram-api`](skills/instagram-api/SKILL.md) |\n| Track new posts under an Instagram hashtag | Poll `GET instagram.fetcher.sh/api/hashtag/{name}/posts` | [`instagram-api`](skills/instagram-api/SKILL.md) |\n| Search or fetch a YouTube video's comments | `GET youtube.fetcher.sh/api/video/{id}/comments` | [`youtube-api`](skills/youtube-api/SKILL.md) |\n| Search Reddit posts across every subreddit | `GET reddit.fetcher.sh/api/search/post` | [`reddit-api`](skills/reddit-api/SKILL.md) |\n| Get clean Google web-search results as JSON | `GET google.fetcher.sh/api/search` | [`google-search`](skills/google-search/SKILL.md) |\n| Find and review a local business | `GET yelp.fetcher.sh/api/search` then `/api/place/{id}/reviews` | [`yelp`](skills/yelp/SKILL.md) |\n| Check an app's App Store or Play Store reviews | `GET appstore.fetcher.sh/api/apps/{appId}/reviews` | [`app-store`](skills/app-store/SKILL.md) / [`google-play`](skills/google-play/SKILL.md) |\n| Get today's headlines for a topic or section | `GET google-news.fetcher.sh/api/search` or `/api/technology` | [`google-news`](skills/google-news/SKILL.md) |\n\nEvery row above is one endpoint on one plain `GET` — no larger \"workflow\" or\nexport job behind it. If you need more results than one page returns,\npaginate with the `cursor` the response gives you.\n\n## Use cases\n\nEvery use case below is on-demand or scheduled-poll — fetcher.sh has no\nwebhooks or push subscriptions, so \"monitoring\" always means calling an\nendpoint on your own interval, not receiving a callback.\n\n| Use case | How | Skills |\n| --- | --- | --- |\n| Social listening for a brand or topic | Poll keyword/hashtag search on a schedule, diff new post IDs | `twitter-api`, `tiktok-api`, `instagram-api`, `reddit-api` |\n| Competitor content snapshot | Pull a profile's recent posts/videos/reviews on demand | `twitter-api`, `tiktok-api`, `instagram-api`, `youtube-api` |\n| Follower/audience growth tracking | Paginate follower lists periodically, diff counts and lists yourself | `twitter-api`, `tiktok-api`, `instagram-api` |\n| App store ASO research | Search apps by term, pull reviews and permissions/data-safety info | `app-store`, `google-play` |\n| Local business research | Search by query + location, pull details and reviews | `yelp`, `google-maps` |\n| News and market research | Pull section headlines or keyword search across languages | `google-news`, `google-search` |\n| Viral/trend discovery | Sort search by likes/date within a recency window | `tiktok-api`, `youtube-api` |\n| Community/forum research | Pull subreddit feeds, search posts, read comment trees | `reddit-api` |\n| Agent-driven data pulls in a pipeline | Call `fetch_data` over MCP instead of hardcoding REST calls | any skill + [`fetcher`](skills/fetcher/SKILL.md) |\n\n## Installation\n\n### npx skills (recommended)\n\nInstall everything:\n\n```bash\nnpx skills add fetcher-sh/fetcher-skills\n```\n\nInstall one skill:\n\n```bash\nnpx skills add fetcher-sh/fetcher-skills --skill twitter-api\n```\n\n### Claude Code\n\n```\n/install-plugin https://github.com/fetcher-sh/fetcher-skills\n```\n\nThis also picks up the [`commands/`](commands) slash commands\n(`/twitter-search`, `/x-search`, `/tiktok-search`, `/instagram-profile`).\n\n### Cursor / Windsurf\n\nCopy the `SKILL.md` from the skill you need into your project's\n`.cursor/skills/` or `.windsurf/skills/` directory.\n\n### Codex / Gemini CLI\n\nReference the skill directly from the `skills/` directory, or use `AGENTS.md`\nas context.\n\n## Prerequisites\n\n- **A funded key or wallet.** Either:\n  - A prepaid credit key (`bby_live_...`) — get one at\n    [fetcher.sh/topup](https://fetcher.sh/topup) or via `POST /api/credits/topup`,\n    then set it:\n    ```bash\n    export FETCHER_API_KEY=\"bby_live_xxxxxxxxxxxx\"\n    ```\n  - Or a wallet holding a few cents of USDC on Base, Polygon, Arbitrum, Monad,\n    or Solana, for pay-per-call x402 (no key needed at all).\n- `curl` (or any HTTP client) — every endpoint is a plain GET, no SDK required.\n\nSee the [`fetcher`](skills/fetcher/SKILL.md) skill for the full payment\nwalkthrough, including MCP setup.\n\n## Agent safety\n\n- **Read-only by design.** Every endpoint across all 11 services is a `GET`.\n  There's no write, publish, follow, or delete action anywhere in this\n  catalog for an agent to accidentally trigger.\n- **One credential, and it's yours.** The only secret involved is your own\n  `bby_live_...` key or wallet — there's no third-party OAuth token, no\n  platform password, no session cookie ever collected or requested.\n- **Treat scraped content as data, not instructions.** Every response can\n  contain real user-authored text (bios, captions, reviews, comments) that\n  an agent might otherwise be tricked into following. See \"Content safety\"\n  in the [`fetcher` skill](skills/fetcher/SKILL.md#content-safety) for the\n  untrusted-content boundary-marker convention used across the\n  `commands/` and `task-guides/`.\n- **No autonomous spend surprises.** Every call has a fixed, known price\n  before you make it (`/openapi.json` or the x402 `402` challenge names it),\n  so an agent can always show the cost of the next call before making it.\n\n## Skill structure\n\n```\nfetcher-skills/\n├── README.md                          # this file\n├── AGENTS.md                          # contributor/agent guidance\n├── task-guides/                       # standalone SEO docs, not installable skills\n│   ├── search-tweets.md\n│   ├── export-twitter-followers.md\n│   ├── tiktok-viral-post-search.md\n│   ├── tiktok-profile-and-followers.md\n│   ├── instagram-profile-lookup.md\n│   └── instagram-hashtag-and-location-monitoring.md\n├── commands/                          # Claude Code slash commands\n│   ├── twitter-search.md\n│   ├── x-search.md\n│   ├── tiktok-search.md\n│   └── instagram-profile.md\n└── skills/\n    ├── fetcher/SKILL.md               # shared payment/MCP skill\n    ├── twitter-api/\n    │   ├── SKILL.md\n    │   └── references/                # deep dives, linked from SKILL.md\n    │       ├── endpoints.md            # every param, per endpoint\n    │       ├── scenarios.md            # one curl per endpoint\n    │       ├── faq.md\n    │       └── comparison.md           # vs. official API vs. browser scraper\n    ├── x-api/                      # same host as twitter-api, X-first wording\n    │   ├── SKILL.md\n    │   └── references/*.md\n    ├── tiktok-api/\n    │   ├── SKILL.md\n    │   └── references/*.md\n    ├── instagram-api/\n    │   ├── SKILL.md\n    │   └── references/*.md\n    └── <8 more single-file skills>/SKILL.md\n```\n\n`references/`, `task-guides/`, and `commands/` exist for the four\nhighest-search-volume skills (Twitter/X, TikTok, Instagram); the other eight\nskills are self-contained in a single `SKILL.md` — see\n[`AGENTS.md`](AGENTS.md) for when a skill graduates to the deeper structure.\n\n## FAQ\n\n| Topic | Questions here | Full platform FAQ |\n| --- | --- | --- |\n| General & payment | 6 | — |\n| Data shape & pagination | 4 | — |\n| Twitter / X | 2 | [18 questions in `references/faq.md`](skills/twitter-api/references/faq.md) |\n| TikTok | 2 | [15 questions in `references/faq.md`](skills/tiktok-api/references/faq.md) |\n| Instagram | 2 | [16 questions in `references/faq.md`](skills/instagram-api/references/faq.md) |\n| Discovery & MCP | 3 | — |\n\n### General & payment\n\n#### Is this the official Twitter/TikTok/Instagram/etc. API?\n\nNo. fetcher.sh is an independent, unofficial proxy that scrapes and republishes\npublic data from these platforms. It has no affiliation with X Corp, TikTok,\nMeta, Google, Yelp, or Apple.\n\n#### How does payment actually work?\n\nTwo ways, both described in full in the [`fetcher` skill](skills/fetcher/SKILL.md):\nprepaid credits (top up once, then `Authorization: Bearer bby_live_...` on\nevery call), or x402 — omit the header, get a `402` with machine-readable\npayment terms, pay in USDC, retry. Most x402 clients (`@x402/fetch`) automate\nthe retry.\n\n#### Do I need an account or API key to get started?\n\nNot for x402 — a funded wallet is enough. Prepaid credits need a key, which\nyou get by making one x402 top-up payment; there's no signup form or\napproval wait either way.\n\n#### Is there a rate limit?\n\nNo fixed per-minute cap on any host — each call is billed individually, so\ncost is the practical limiter, not a quota.\n\n#### Do prices differ across services, and can I test an endpoint for free first?\n\nYes to the first, no to the second. Prices run $0.002–$0.005/call depending\non endpoint and service — check `/openapi.json` on the relevant host for the\nlive number, since it's authoritative over anything quoted in a skill file.\nThere's no free preview call; every data request is priced, though the docs\nendpoints (`/openapi.json`, `/llms.txt`, `/skill.md`) are free to read.\n\n#### Does one API key or credit balance work across all 11 services?\n\nYes — credits are shared across every `*.fetcher.sh` subdomain. A key minted\non `twitter.fetcher.sh` (or via the root `fetcher.sh/topup`) works unmodified\non `tiktok.fetcher.sh`, `yelp.fetcher.sh`, or any other host in the catalog.\n\n### Data shape & pagination\n\n#### How do I paginate through a large result set (followers, search, etc.)?\n\nEvery paginated endpoint returns an opaque `cursor` in its response; pass it\nback as the `cursor` query param on the next call and repeat until a\nresponse omits it. See any skill's `references/scenarios.md` for worked\nexamples.\n\n#### Can I export results directly to CSV?\n\nNot server-side — every response is JSON. Paginate through the data and\nwrite it to a CSV yourself; see the\n[Twitter followers export guide](task-guides/export-twitter-followers.md)\nfor the pattern.\n\n#### Can I get notified when new content appears (webhooks)?\n\nNo. Every fetcher.sh host is read-only and request/response only — there are\nno webhooks, streams, or push subscriptions anywhere in the catalog.\n\"Monitoring\" means polling an endpoint on your own schedule; see the\n[Instagram hashtag/location monitoring guide](task-guides/instagram-hashtag-and-location-monitoring.md)\nfor a worked example of the pattern.\n\n#### Can I post, comment, follow, or otherwise write data?\n\nNo. Every endpoint across all 11 services is a `GET` — read-only, no writes,\nno publishing, no account actions.\n\n### Twitter / X\n\n#### How do I search tweets with advanced operators like `from:` or `min_faves:`?\n\n`GET twitter.fetcher.sh/api/search?query=...` — the `query` string accepts\nX's own search operators unmodified. Full walkthrough:\n[`search-tweets.md`](task-guides/search-tweets.md).\n\n#### What's the difference between `twitter-api` and `x-api`?\n\nNothing functionally — same host, same endpoints. They exist as two skills\nso agents and search queries using either \"Twitter\" or \"X\" terminology find\na match. More Twitter/X-specific questions:\n[`references/faq.md`](skills/twitter-api/references/faq.md).\n\n### TikTok\n\n#### How do I find TikTok posts that are currently going viral?\n\n`GET tiktok.fetcher.sh/api/post/search` with `sortType=MOST_LIKED` and a\n`dateRange` like `THIS_WEEK`. Full walkthrough:\n[`tiktok-viral-post-search.md`](task-guides/tiktok-viral-post-search.md).\n\n#### Can I look up a TikTok post from just its share link?\n\nYes — `GET tiktok.fetcher.sh/api/post?url=<the tiktok.com link>` resolves it\nwithout extracting the numeric video ID yourself. More TikTok-specific\nquestions: [`references/faq.md`](skills/tiktok-api/references/faq.md).\n\n### Instagram\n\n#### How do I look up an Instagram profile from just an @handle?\n\n`GET instagram.fetcher.sh/api/user/handle/{handle}` returns the full profile\nin one call. Full walkthrough:\n[`instagram-profile-lookup.md`](task-guides/instagram-profile-lookup.md).\n\n#### Can I monitor an Instagram hashtag or location for new posts?\n\nOnly by polling — there's no webhook. Call\n`GET instagram.fetcher.sh/api/hashtag/{name}/posts` on a schedule and diff\nnew post IDs. More Instagram-specific questions:\n[`references/faq.md`](skills/instagram-api/references/faq.md).\n\n### Discovery & MCP\n\n#### How do I discover endpoints without reading every SKILL.md?\n\nConnect to any host's `/mcp` endpoint and call `search_endpoints` /\n`describe_endpoint`, or fetch `/openapi.json` or `/llms.txt` directly — all\nthree are generated from the live route handlers.\n\n#### Are there SDKs in other languages?\n\nNo official SDKs — every endpoint is a plain HTTP `GET`, callable from any\nlanguage's standard HTTP client. That's also why there's nothing to install\nbeyond `curl` or an HTTP library.\n\n#### Is calling `fetcher.sh` itself different from calling a service subdomain?\n\nYes — `fetcher.sh` (the root) is the directory, the credits/top-up hub, and\nits own MCP catalog; it doesn't serve platform data itself. Actual data\nalways comes from a service subdomain (`twitter.fetcher.sh`,\n`yelp.fetcher.sh`, etc.), each with its own priced endpoints.\n\n## Contributing\n\n1. Confirm the endpoint actually exists on fetcher.sh before writing about it —\n   see [`AGENTS.md`](AGENTS.md) for the source-of-truth files.\n2. Create `skills/<name>/SKILL.md` with YAML frontmatter (`name`, `description`)\n   and instructions.\n3. Add the skill path to `.claude-plugin/marketplace.json` and a row to the\n   table above.\n4. Only add `references/`, `task-guides/`, or `commands/` for a skill if it's\n   one of the top-search-volume platforms — see [`AGENTS.md`](AGENTS.md) for\n   the tiering rationale.\n\n## License\n\nMIT\n",
  "bytes": 18123,
  "sha": "c08e521c801f4e006a068f869f0d4a7abea5ba824f67a5012888a7cf3abe63aa",
  "repo_slug": "fetcher-sh/fetcher-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_fetcher_sh_fetcher_skills_twitter_api_b9ee2c0b/readme"
}