# Refetcher

> Refetcher is a pay-as-you-go social media scraping API for retrieving real-time public Instagram, TikTok, Facebook, X (Twitter), and YouTube data through one normalized HTTP interface.

## Core facts

- Pricing is usage-based ($0.90 per 1,000 successful scrapes), not a monthly subscription.
- There is no monthly minimum spend.
- Purchased funds and bonus credits do not expire or reset at month-end.
- Top-ups of $200 or more receive 5% bonus credit; top-ups of $500 or more receive 10% bonus credit.
- Failed scrapes are not charged.
- New accounts receive 3,000 free scrapes without a card, provided as $2.70 in trial credit at the current rate.
- Refetcher combines direct access and residential proxy routes across its scraping services. The resulting rolling success rate is published on the public status page.
- Current uptime, scraper success rate, latency, and incident information are published on the public status page.
- Refetcher is built for developers, marketing and influencer agencies, and data teams that need public social media metrics at scale.

## Supported data

- Instagram public posts, Reels, profiles, and post comments (type instagramComments: 14 public top-level comments per full page, up to 25 pages per request, native order and a 24-hour cursor)
- Instagram profiles include the Posts feed by default, including cursor requests; use `includeRecentPosts: false` for metadata only. `recentVideos` contains only the videos from `recentPosts`. Pages and cursors use the same nullable count fields: `views` equals `playCount`, and `viewCount` is a separate value. Numeric likes and plays, including zero, remain present even when `media.likeAndViewCountsDisabled` is true; unavailable counts, comments, publication times and optional profile metadata remain null.
- Individual Instagram post/Reel requests return plays (`metrics.views`, `media.playCount`) and a separate, usually lower view count (`media.viewCount`). When Instagram does not make the view count public, `media.viewCount` is null and `media.viewCountUnavailableReason` is `not_publicly_available`; `media.likeAndViewCountsDisabled` reports whether the creator hid like and view counts.
- TikTok public videos and creator profiles, including carousels, with exact view, like, comment, share and save counts on each video or carousel
- TikTok public post comments and replies: full available comment text, comment likes, reply counts, authors and dates, with pages and cursors. Use `type: "tiktokComments"` or `type: "tiktokCommentReplies"`; post engagement counts alone do not include comment text.
- Facebook public posts, Reels, videos, photos, carousels, and profiles
- X (Twitter) public posts with exact views, likes, replies, reposts, bookmarks and quotes, plus profiles with up to 125 latest or popular posts per request (5 per page)
- YouTube videos and Shorts with exact views, likes and comments and optional comments, plus channels with up to 300 latest videos per request (12 per page) and a 24-hour cursor to continue
- YouTube video and Short comments and replies: full comment text, exact likes when available plus the original rounded display, reply counts, authors and YouTube's relative posted time, 20 per page, up to 25 pages per request, native Top or Newest order for top-level comments and native order for replies, and an opaque encrypted 24-hour cursor. Use `type: "youtubeComments"` or `type: "youtubeCommentReplies"` with `commentId`; video requests can still include up to 100 newest comments with `includeRecentComments`
- Common metrics include views, likes, comments, shares, saves, author details, and publication metadata when available

## Primary pages

- [Homepage](https://www.refetcher.com/): Product overview, supported platforms, differentiators, and demo
- [Instagram Scraper API](https://www.refetcher.com/instagram-scraper-api): Instagram post, Reel, and profile data, response fields, pricing, and FAQ
- [Facebook Scraper API](https://www.refetcher.com/facebook-scraper-api): Facebook post, video, Reel, and profile data, response fields, pricing, and FAQ
- [TikTok Scraper API](https://www.refetcher.com/tiktok-scraper-api): TikTok video, profile, comment and reply data, response fields, pricing, and FAQ
- [TikTok comments](https://www.refetcher.com/docs#req-tiktok-comments) and [comment replies](https://www.refetcher.com/docs#req-tiktok-comment-replies): Root POST request types, pagination, response fields, sorting limits and billing
- [YouTube comments](https://www.refetcher.com/docs#req-youtube-comments) and [comment replies](https://www.refetcher.com/docs#req-youtube-comment-replies): Root POST request types, pagination, sort order, response fields, errors and billing
- [YouTube Scraper API](https://www.refetcher.com/youtube-scraper-api): YouTube video, Shorts, and channel data, response fields, pricing, and FAQ
- [X (Twitter) Scraper API](https://www.refetcher.com/x-twitter-scraper-api): X (Twitter) post and profile data, response fields, pricing, and FAQ
- [Network and infrastructure](https://www.refetcher.com/network): Residential proxy network size, request pipeline, blocking avoidance, scale, and reliability
- [Pricing](https://www.refetcher.com/pricing): Pay-as-you-go rate, top-up bonuses, and billing FAQ
- [API documentation](https://www.refetcher.com/docs): Authentication, request formats, endpoints, responses, retries, and examples
- [Service status](https://app.refetcher.com/status.html): Published uptime, success rate, latency, and incident history
- [Contact](https://www.refetcher.com/contact): Support and sales, typical response within 2 hours
- [Privacy](https://www.refetcher.com/privacy)
- [Terms](https://www.refetcher.com/terms)
- [Refund policy](https://www.refetcher.com/refunds)

## API

- Base URL: https://api.refetcher.com/
- Authentication: `X-API-Key: pc_live_...` or `Authorization: Bearer pc_live_...`
- Primary request pattern: POST one target or a batch to the root URL and receive normalized JSON
- TikTok comments use POST https://api.refetcher.com/ with `{"type":"tiktokComments","url":"https://www.tiktok.com/@creator/video/1234567890123456789","pages":2}`. Replies use the same root URL with `{"type":"tiktokCommentReplies","url":"https://www.tiktok.com/@creator/video/1234567890123456789","commentId":"1234567890123456789","pages":1}`. Replies accept exactly one post and a numeric-string `commentId` for the parent comment. See the comments and replies documentation linked above.
- TikTok comment inputs accept full video or photo/carousel URLs and supported `vm.tiktok.com`, `vt.tiktok.com` and `tiktok.com/t/` share links. Top-level comments accept `url` or `urls` within the account batch limit, but every supplied comment-post target must be valid: a malformed TikTok comments batch returns free HTTP 400 before any target is scraped. Replies and cursor requests accept one post.
- TikTok comment `pages` accepts 1–25, default 1, with up to 20 comments per source page. Short pages, deduplication and TikTok's public availability can reduce the number returned. Continue with `pageInfo.endCursor` as `after` when `pageInfo.hasNextPage` is true; `cursor` and `endCursor` are input aliases. Send the token unchanged within 24 hours on the same post and, for replies, the same parent `commentId`. Top-level and reply cursors are separate. Invalid, expired, conflicting or mismatched cursors return free HTTP 400. Terminal pages return `hasNextPage: false` and `endCursor: null`.
- TikTok comment results have `type: "comments"`, `post.id`, `post.url`, `parentCommentId`, `comments`, `totalCount`, `sort`, `sortScope` and `pageInfo`. Each comment includes `id`, full `text`, `createdAt`, `likeCount`, `replyCount`, parent/direct-reply IDs, author details and nullable creator/pinned signals. Missing optional values remain null. Long native text is preserved; result-size limits stop before a whole source page and retain continuation rather than cutting a comment. TikTok may expose only a subset of public comments; neither `totalCount` nor a cursor guarantees retrieval of every comment.
- TikTok comment `sort` defaults to `relevant`, preserving TikTok's order with `sortScope: "tiktok_order"`. `latest` and `likes` sort only the comments returned in the current request, descending by date or like count, with `sortScope: "returned_comments"`. They do not select the globally newest or most-liked comments on the post, and they do not change the cursor's underlying continuation order.
- TikTok comments and replies charge one unit per populated page delivered. Successful empty responses and failed requests cost zero; requesting more pages than are delivered does not add charges. Confirmed unavailable posts return HTTP 404 `private_or_removed`; confirmed public age restrictions return HTTP 403 `age_restricted`. Ambiguous retrieval failures remain technical errors. HTTP 429 can indicate an active request or failure cooldown; use `retryAfterSeconds` when returned. Failed and empty comment requests release their unused reservation.
- YouTube comments use POST https://api.refetcher.com/ with `{"type":"youtubeComments","url":"https://www.youtube.com/watch?v=VIDEO_ID","pages":2,"sort":"latest"}`. Replies use `{"type":"youtubeCommentReplies","url":"https://www.youtube.com/watch?v=VIDEO_ID","commentId":"TOP_LEVEL_COMMENT_ID"}`, optionally with the comment's `replyCursor` as `after`; reply sort accepts only `relevant`. Copy opaque encrypted `youtube:comments:v2:` cursors unchanged; they bind the video, sort and reply parent for 24 hours. `likedByAuthor` is the native channel-heart state (true, false or null); reply rows have `replyCount: null`. `totalCount` is an exact integer when available, otherwise null; `totalCountText` preserves the original count display without expanding rounded values. Each delivered page of up to 20 comments or replies is one unit; empty results and failures are free. Unavailable videos return 404 `private_or_removed`; age, region, copyright, sign-in and comments-off restrictions return 403 with their own categories. Invalid options or cursors return 400 without a charge; 429 can indicate the shared active-request or failure cooldown
- X profile feeds return posts and exclude authored replies. X may return reposts in the public post feed; there is no separate reply, repost or media-feed selector. `sort` defaults to newest-first `latest`, while `popular` selects X's public popularity-ranked posts. Both sorts use up to 5 posts per customer page; `pages` accepts 1–25 per request. When `pageInfo.recentPosts.hasNextPage` is true, send its `endCursor` as `after` to retrieve the next window. `pages` also controls each continuation response. Returned items expose `isPinned`.
- X profile cursors expire after 24 hours and accept exactly one profile with the same `sort` and `includeRetweets` setting. `cursor` and `endCursor` are accepted aliases for `after`; send the returned value unchanged. `includeRecentPosts` defaults to true for continuation, and explicit false returns HTTP 400. Invalid, expired, conflicting, mismatched, or changed-boundary cursors return HTTP 400 without a charge; restart without a cursor after a boundary change. `hasNextPage` is true only with a usable non-null `endCursor`. Available coverage depends on X's public feed, with no guarantee of all historical posts. A terminal or non-resumable response has `hasNextPage: false` and `endCursor: null`; partial requested coverage may be `incomplete: true`. `hasMorePosts` alone does not guarantee continuation.
- X captions use complete native own-text fields when available. A verified retweet caption expands the literal native `RT @handle:` prefix with the original's full native body, preserving the requested wrapper's identity, author, and metrics. Quote and reply text never replace the requested caption.
- Confirmed missing/deleted X posts and missing profiles return the non-retryable `private_or_removed` category. A response containing only unavailable targets returns HTTP 404; a mixed batch with successes remains HTTP 200. Temporary or ambiguous retrieval failures retain retryable error categories.
- If an X post URL fails, the same API key must wait 3 minutes to request that URL again. Earlier retries return HTTP 429 `rate_limited` with `retryAfterSeconds`; failed requests are free. Successful URLs can be fetched again immediately, and profile cursor requests are outside this failure cooldown.
- X profile cursor chains support up to 1,000 posts across their requests.
- Default batch limit: 10 targets; service hard limit: 50 targets
- Batch limits are account-scoped: every current and future API key on an account inherits the same configured limit; per-key limit values are not authorization sources.
- Batch execution is orchestrated internally: every valid customer URL gets its own independent downstream scrape invocation or target-scoped routing sequence on Instagram, TikTok, YouTube, X, and Facebook; all 50 initial operations may start concurrently, retries never combine targets, and the response always preserves input URL order.
- Invalid or unsupported links fail individually with `bad_url` in ordered `results`; valid links in the batch continue. Invalid items cost nothing and do not reserve balance. A batch with at least one success returns HTTP 200; a batch containing only invalid targets returns HTTP 400 with `results` and `summary`. TikTok comments are the exception described above: a malformed comment-post target rejects the whole batch with free HTTP 400 before any target is scraped.
- For Instagram, TikTok, Facebook, and X, invalid `username`/`usernames` entries also retain individual `bad_url` results, including repeated invalid names, blanks, and non-string array entries. Invalid results carry the known platform and `type: "profile"`; `url` is the trimmed submitted name or null for a non-string entry. Valid names retain canonical profile URLs and existing deduplication. Results follow target order after normalization; invalid username entries are never silently skipped, scraped, charged, or reserved.
- The account batch limit applies before invalid targets are excluded. Requests over the limit, malformed requests, and invalid shared options or cursors remain request-level HTTP 400 errors; no target is scraped or charged.
- Public status: GET https://api.refetcher.com/status
- JSON health check: GET https://api.refetcher.com/health

Use the linked pages as the canonical sources for current product, pricing, technical, and reliability information.

- YouTube channel upload pagination: `pages` accepts 1–25 (up to 12 uploads per page, 300 per request). Upload lists include top-level `pageInfo`; pass its `endCursor` as `after` with the same single channel to continue. `pages` and `after` work together. Cursors expire after 24 hours; terminal pages have `hasNextPage: false` and `endCursor: null`. Explicit `recentVideosLimit`/`videoLimit`/`limit` counts retain precedence over `pages`. See https://www.refetcher.com/docs#youtube-pagination.