> ## Documentation Index > Fetch the complete documentation index at: https://docs.tovuk.com/llms.txt > Use this file to discover all available pages before exploring further. # Scraper API > Use Tovuk Scrapers, Requests, Results, and Records from API or CLI. Tovuk Scrapers read public data and store the output as Results. Use Requests to start work, poll status, and fetch Records later without building your own storage layer. Scraper requests are public data only. Do not send cookies, passwords, account tokens, private session data, private account content, private repository credentials, or proxy URLs. Scraper Requests require paid billing. Catalog reads are public, but creating a Request returns `payment_required` until billing is active. ## Pricing Tovuk charges per successful stored Record and deducts the final cost from the account balance automatically. Monthly plans provide balance first: Plus includes `$20`, Pro includes `$120`, and Max includes `$300`. Use the live catalog as the source of truth: ```sh theme={"dark"} tovuk scraper list --json ``` | Scraper | Unit | Price per 1,000 results | | ------------------- | ------ | ----------------------: | | `reddit` | record | `$0.70` | | `github` | record | `$0.60` | | `google-maps` | place | `$1.20` | | `amazon` | record | `$1.40` | | `alibaba` | record | `$1.50` | | `temu` | record | `$1.60` | | `etsy` | record | `$1.20` | | `apple-app-store` | record | `$1.40` | | `google-play-store` | record | `$1.40` | | `trendyol` | record | `$1.40` | | `hepsiburada` | record | `$1.40` | | `youtube` | record | `$1.40` | | `zillow` | record | `$1.50` | | `indeed` | record | `$1.20` | | `trustpilot` | record | `$1` | | `linkedin` | record | `$0.90` | | `tiktok` | record | `$1.70` | | `instagram` | record | `$0.80` | | `x` | post | `$0.30` | ## Names * Scraper: a public-data source such as `github`, `google-maps`, `amazon`, or `reddit`. * Request: one paid scraper run. * Results: stored output for one Request. * Record: one JSON item inside Results. ## CLI ```sh theme={"dark"} tovuk scraper list --json tovuk scraper health --json tovuk scraper show github --json tovuk request create github '{"query":"mcp server","language":"Rust","limit":50}' --json tovuk request create github '{"operation":"opportunities","query":"agent skills registry","limit":25}' --json tovuk request create github '{"operation":"codeSearch","query":"serde language:Rust","maxRepos":3,"limit":25}' --json tovuk request create github '{"operation":"codeSearch","query":"StreamableHTTPClientTransport","language":"TypeScript","repo":"modelcontextprotocol/typescript-sdk","path":"examples/client/src","limit":25}' --json tovuk request create github '{"url":"https://github.com/rust-lang/rust/issues/1"}' --json tovuk request create github '{"operation":"watchers","repo":"rust-lang/rust","limit":50}' --json tovuk request create github '{"operation":"file","repo":"rust-lang/rust","path":"README.md","contentMaxChars":2000}' --json tovuk request create github '{"operation":"trendingDevelopers","language":"rust","since":"weekly","limit":25}' --json tovuk request create github '{"operation":"marketplace","appsUrls":[{"url":"https://github.com/marketplace/codecov"}],"limit":10}' --json tovuk request create reddit '{"subreddit":"rust","sort":"new","limit":50}' --json tovuk request create reddit '{"operation":"subreddit-profile","community":"rust"}' --json tovuk request create reddit '{"query":"rust lang","contentType":"both","autoDiscoverSubreddits":true,"maxSubreddits":5,"fields":["type","id","url","title","bodyText","score"],"maxResults":50}' --json tovuk request create reddit '{"operation":"comments","url":"https://www.reddit.com/r/rust/comments/POST_ID/example/","commentSort":"top","limit":100}' --json tovuk request create linkedin '{"operation":"post-search","query":"b2b sales","sort_type":"date_posted","author_company_urns":"1035","limit":25}' --json tovuk request create linkedin '{"operation":"company-employees","identifier":"https://www.linkedin.com/company/google/","job_title":"engineer OR developer","max_employees":50}' --json tovuk request create google-maps '{"searchTerms":["coffee shops"],"locationQuery":"Seattle, WA","limit":25,"scrapeContacts":true}' --json tovuk request create amazon '{"operation":"search","query":"mechanical keyboard","countryCode":"DE","deliveryLocation":"10115","limit":25,"includeReviews":true}' --json tovuk request create alibaba '{"operation":"search","query":"stainless bottle","limit":25,"includeSupplierVerification":true}' --json tovuk request create temu '{"operation":"search","query":"desk lamp","limit":25,"includeSalesData":true}' --json tovuk request create etsy '{"operation":"search","query":"linen wall art","limit":25,"includeShopDetails":true}' --json tovuk request create apple-app-store '{"appIds":["6448311069"],"country":"us","includeAppInfo":true,"limit":1}' --json tovuk request create google-play-store '{"appIds":["com.openai.chatgpt"],"country":"us","lang":"en","includeAppInfo":true,"limit":1}' --json tovuk request create youtube '{"operation":"search","query":"open source database tutorial","country":"US","language":"en-US","limit":10}' --json tovuk request create zillow '{"operation":"search","query":"Austin TX","includePhotos":true,"limit":10}' --json tovuk request create indeed '{"operation":"search","query":"rust engineer","location":"Remote","includeCompanyInfo":true,"limit":10}' --json tovuk request create trustpilot '{"operation":"search","query":"openai","includeReviews":true,"limit":10}' --json tovuk request create trendyol '{"operation":"search","query":"kablosuz kulaklik","countryCode":"TR","currency":"TRY","limit":10}' --json tovuk request create hepsiburada '{"operation":"search","query":"kablosuz kulaklik","countryCode":"TR","currency":"TRY","limit":10}' --json tovuk request create tiktok '{"operation":"search","query":"rust programming","outputFields":["id","desc","author.uniqueId","stats.playCount"],"limit":30}' --json tovuk request create tiktok '{"operation":"sound","soundUrls":["https://www.tiktok.com/music/original-sound-1234567890"],"limit":30}' --json tovuk request create instagram '{"username":"instagram","operation":"profile","limit":50}' --json tovuk request create instagram '{"url":"https://www.instagram.com/reel/SHORTCODE/","operation":"comments","limit":100}' --json tovuk request create x '{"query":"rust lang","product":"Latest","limit":100}' --json tovuk request create x '{"url":"https://x.com/openai/status/1234567890","limit":1}' --json tovuk request show --json tovuk request results --json tovuk request cancel --json ``` Use `--limit ` on `tovuk request create` to add or override `input.limit`. Use `--limit ` and `--cursor ` on `tovuk request list` and `tovuk request results` to page through Requests and stored Records. Use `tovuk scraper health --json` before heavy scraping to inspect public data-source readiness without sending private account material. ## API ```http theme={"dark"} GET /v1/data-sources GET /v1/data-sources/health GET /v1/data-sources/{data_source} POST /v1/requests GET /v1/requests GET /v1/requests/{request_id} POST /v1/requests/{request_id}/cancel GET /v1/requests/{request_id}/results ``` Create a Request: ```json theme={"dark"} { "scraper": "github", "input": { "query": "mcp server", "language": "Rust", "limit": 50 } } ``` Create an X Request: ```json theme={"dark"} { "scraper": "x", "input": { "query": "rust lang", "product": "Latest", "limit": 100 } } ``` X also accepts a public `x.com` or `twitter.com` post/profile URL, `username`, `userId`, or `tweetId`. Tovuk stores canonical public input fields and manages public-data retrieval. Create a GitHub Request: ```json theme={"dark"} { "scraper": "github", "input": { "operation": "opportunities", "query": "agent skills registry", "limit": 25 } } ``` Create a GitHub Marketplace Request: ```json theme={"dark"} { "scraper": "github", "input": { "operation": "marketplace", "appsUrls": [ { "url": "https://github.com/marketplace/codecov" } ], "limit": 10 } } ``` Create a broad GitHub Code Search Request: ```json theme={"dark"} { "scraper": "github", "input": { "operation": "codeSearch", "query": "serde language:Rust", "maxRepos": 3, "limit": 25 } } ``` Create a repo-scoped GitHub Code Search Request: ```json theme={"dark"} { "scraper": "github", "input": { "operation": "codeSearch", "query": "StreamableHTTPClientTransport", "language": "TypeScript", "repo": "modelcontextprotocol/typescript-sdk", "path": "examples/client/src", "limit": 25 } } ``` Create a GitHub File Request: ```json theme={"dark"} { "scraper": "github", "input": { "operation": "file", "repo": "rust-lang/rust", "path": "README.md", "contentMaxChars": 2000 } } ``` Create a GitHub Watchers Request: ```json theme={"dark"} { "scraper": "github", "input": { "operation": "watchers", "repo": "rust-lang/rust", "limit": 50 } } ``` GitHub accepts public repository search queries, public `github.com` repository URLs, `owner/repo` names, `language`, `topic`, `operation: "trending"`, `operation: "trendingDevelopers"`, `operation: "opportunities"`, `operation: "codeSearch"` with public code queries plus optional `language`, `repo`, `filename`, `path`, or GitHub-style query qualifiers such as `repo:owner/name`, `language:Rust`, `filename:Cargo.toml`, or `path:src`. Omit `repo` to let Tovuk discover candidate public repositories first, and use `maxRepos` to cap repository archive scans. `operation: "issue"` for public issue detail URLs or `number`, and `operation: "pullRequest"` for public pull request detail URLs or `number`. It also accepts `operation: "file"` with public `repo` plus `path`, public `github.com` blob URLs, or public `raw.githubusercontent.com` file URLs, `operation: "stargazers"`, `operation: "watchers"`/`"subscribers"`, and `operation: "forkers"` for public repository audience pages. Use `operation: "trendingDevelopers"` for trending developer lists. Use `operation: "marketplace"` with `query` or `searchQuery` for Marketplace search, `marketplaceUrls`, and `appsUrls` for public Marketplace app pages. Tovuk stores canonical public input fields and returns repository-shaped, file-shaped, issue-shaped, pull-request-shaped, developer-shaped, or Marketplace app Records. Business and ecommerce scrapers use the same Request shape shown in the CLI examples above: | Scraper | Public inputs | Operations | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `google-maps` | place URLs, search URLs, shared list URLs, place ids, search terms, location context, review filters, contact and image flags | `search`, `place`, `reviews`, `list` | | `amazon` | search terms, product URLs, ASINs, seller URLs, category URLs, bestseller targets, country-specific Amazon marketplace targets, delivery-location or postal-code hints, price filters, review and offer flags | `search`, `product`, `reviews`, `offers`, `seller`, `bestsellers`, `asins`, `questions`, `price-tracker` | | `alibaba` | search terms, product URLs, supplier URLs, category URLs, RFQ targets, reverse-image inputs, MOQ and price-tier options | `search`, `product`, `supplier`, `category`, `rfq`, `reverse-image`, `price-tiers` | | `temu` | search terms, product URLs, listing URLs, category URLs, review options, ad-library targets, sold-count and variant flags | `search`, `product`, `listings`, `category`, `reviews`, `ad-library`, `price-tracker` | | `etsy` | search terms, listing URLs, shop URLs, review targets, keyword-research options, seller-intelligence and customer-photo flags | `search`, `listing`, `shop`, `reviews`, `keywords`, `seller-intel`, `customer-photos` | | `apple-app-store` | app IDs, app URLs, search terms, country, language, chart/category, reviews, developer, version, rating, screenshot, and app-store optimization flags | `search`, `app`, `reviews`, `rankings`, `developer`, `keywords` | | `google-play-store` | package names, app URLs, search terms, country, language, category/chart, reviews, developer, permissions, data-safety, rating, install, screenshot, and app-store optimization flags | `search`, `app`, `reviews`, `rankings`, `developer`, `keywords`, `permissions`, `data-safety` | | `youtube` | search queries, start URLs, video IDs, channel URLs or handles, playlist IDs, comments, transcript languages, country, language, shorts, trending, download-intent, and public email flags | `search`, `video`, `channel`, `playlist`, `comments`, `transcript`, `shorts`, `trending`, `download`, `email` | | `zillow` | search URLs, address, ZIP or city queries, property URLs, sale/rent/sold mode, price, beds, baths, foreclosure, agent, photo, and market options | `search`, `property`, `rentals`, `sales`, `sold`, `agents`, `foreclosures`, `photos`, `markets` | | `indeed` | query, location, country, radius, job URLs, company URLs, salary filters, job type, posted date, remote, and duplicate policy | `search`, `job`, `company`, `salaries`, `resume` | | `trustpilot` | business URLs or domains, category URLs, review filters, stars, date range, language, country, reply, reviewer, and sentiment-style flags | `search`, `business`, `reviews`, `categories`, `reviewer` | | `trendyol` | search terms, product URLs, seller URLs, category URLs, review mode, price filters, seller intelligence, Turkey locale, and public contact flags | `search`, `product`, `listings`, `reviews`, `seller`, `emails` | | `hepsiburada` | search terms, product URLs, category URLs, merchant URLs, review mode, barcode/search hints, Turkey locale, and marketplace filters | `search`, `product`, `listings`, `reviews`, `merchant` | Tovuk accepts public inputs for Google Maps, ecommerce, app-store, video, real-estate, jobs, and review reads, and stores visible public records only. Ecommerce operation inputs may use common Apify-style aliases such as `best_sellers`, `adLibrary`, `Vendor`, `seller-intelligence`, `postalCode`, or `zipCode`; saved requests return the canonical operation token shown in the table and normalize postal aliases to `deliveryLocation`. Use `tovuk scraper show --json` to inspect exact `inputSchema` caps. Current ecommerce caps are 50 search terms, 200 broad URL or product URL values, 100 seller, shop, or category URL values, 200 product IDs or ASINs, 100 category IDs, 512 characters for search text, 2,048 characters for URLs, and 128 characters for generated product or category IDs. Ecommerce Records include `requestedFeatures` and `featureCoverage`. Use `featureCoverage` to see whether each Apify-style feature flag was extracted, not found in the fetched public HTML, partially extracted, or accepted for compatibility while a platform-specific parser is still needed. When public metadata or visible page text provides them, ecommerce Records also include fields such as `tags`, `keywords`, `questionSamples`, `customerPhotoUrls`, `minimumOrderQuantity`, `rfqText`, `deliveryLocation`, `resultPosition`, and `adPosition`. Create a Reddit Request: ```json theme={"dark"} { "scraper": "reddit", "input": { "query": "rust lang", "contentType": "both", "autoDiscoverSubreddits": true, "maxSubreddits": 5, "fields": ["type", "id", "url", "title", "bodyText", "score"], "maxResults": 50 } } ``` Reddit accepts public subreddit names, public search queries, public Reddit post URLs, public subreddit URLs, `postId`, and public usernames. Use `operation: "subreddit-profile"` with `community`, `subreddit`, or a public subreddit URL when you need one community metadata Record with title, description, sidebar text, member counts when present, rules, icons, and public flags. Use `contentType: "posts"`, `contentType: "comments"`, or `contentType: "both"` to select post search, comment search, or both result types in one Request. Set `autoDiscoverSubreddits: true` with `maxSubreddits` on site-wide search to discover relevant public communities first, then search across them while keeping total Records capped by `limit` or `maxResults`. Add `fields` when you want compact Records with only selected top-level JSON fields. Operations include `subreddit`, `subreddit-profile`, `search`, `search-comments`, `search-communities`, `search-users`, `subreddit-users`, `post`, `comments`, `user`, `user-posts`, `user-comments`, `user-overview`, `popular`, and `all`. For direct post or comment requests, `commentSort` aliases `sort` and supports public Reddit comment ordering. Tovuk stores canonical public input fields and manages public-data retrieval. Create a LinkedIn Post Search Request: ```json theme={"dark"} { "scraper": "linkedin", "input": { "operation": "post-search", "query": "b2b sales", "sort_type": "date_posted", "date_filter": "past-week", "author_company_urns": "1035", "author_industry_urns": "4,43", "author_job_title": "founder", "limit": 25 } } ``` Create a LinkedIn Company Employees Request: ```json theme={"dark"} { "scraper": "linkedin", "input": { "operation": "company-employees", "identifier": "https://www.linkedin.com/company/google/", "job_title": "engineer OR developer", "max_employees": 50 } } ``` LinkedIn accepts public job search URLs, job ids, company URLs or names, profile URLs or public identifiers, people-search filters, post URLs, post-search terms, content filters, public author/member/company/industry ids, and company employee filters. Operations include `jobs`, `job`, `company`, `company-search`, `company-employees`, `profile`, `profile-search`, `profile-posts`, `profile-comments`, `profile-reactions`, `post`, `post-comments`, `post-reactions`, `post-reshares`, `post-search`, and `company-posts`. Public input fields such as `keyword`, `searchQuery`, `profileUrls`, `publicIdentifiers`, `targetUrls`, `sort_type`, `date_filter`, `company_urns`, `member_urns`, `author_company_urns`, `author_industry_urns`, `author_job_title`, `maxPosts`, `total_posts`, `identifier`, `job_title`, and `max_employees` normalize onto the same public options. Create a TikTok Request: ```json theme={"dark"} { "scraper": "tiktok", "input": { "operation": "search", "query": "rust programming", "outputFields": ["id", "desc", "author.uniqueId", "stats.playCount"], "limit": 30 } } ``` Create a TikTok Sound Request: ```json theme={"dark"} { "scraper": "tiktok", "input": { "operation": "sound", "soundUrls": ["https://www.tiktok.com/music/original-sound-1234567890"], "limit": 30 } } ``` TikTok accepts public video URLs, profile URLs, usernames, video ids, hashtags, music ids, place ids, Ads Library URLs, Shop URLs, public Shop ids, public product ids, public search terms, and operations such as `video`, `profile`, `videos`, `search`, `hashtag`, `music`, `comments`, `followers`, `following`, `ads`, `shop`, and `location`. Use `fields`, `outputFields`, `includeFields`, or `fieldProjection` for safe dot-path projection. Tovuk returns projected values in `selectedFields`, `selectedItems`, `selectedComments`, or `selectedUsers` without executing customer JavaScript. Public-input aliases such as `profileUrls`, `handles`, `queries`, `userSearch`, `videoSearch`, `sound`, `soundUrls`, `musicUrls`, `soundIds`, `region`, `startDate`, `endDate`, `minLikes`, `maxLikes`, `downloadVideos`, `downloadSubtitles`, and `transcribeVideos` normalize onto the same public options; cookies, passwords, tokens, session data, and proxy URLs are not accepted. Create an Instagram Request: ```json theme={"dark"} { "scraper": "instagram", "input": { "operation": "comments", "url": "https://www.instagram.com/reel/SHORTCODE/", "limit": 100 } } ``` Instagram accepts public profile URLs, post URLs, reel URLs, hashtag URLs, `username`, `shortcode`, `mediaId`, `hashtag`, `query`, and operations `profile`, `post`, `reel`, `comments`, `hashtag`, and `search`. Tovuk stores canonical public input fields and manages public-data retrieval. Every Request stores its public input, status, estimated cost when `limit` is known, final cost, `resultsUrl`, and `agentInstruction`. ## Public Data Only Do not send cookies, passwords, account tokens, private session data, or private account content. Send public URLs, public search terms, public profile handles, public repository names, public place ids, and public company or domain inputs only. For X Requests, never send login cookies, account credentials, session tokens, or proxy URLs. Send only public X targets and public search filters. For GitHub Requests, never send GitHub tokens, personal access tokens, private repository URLs, git credentials, cookies, session tokens, or proxy URLs. For Google Maps Requests, never send private account data, private saved-place lists, cookies, Google account credentials, session tokens, or proxy URLs. For ecommerce Requests, never send marketplace account cookies, buyer or seller account credentials, order history, private cart data, session tokens, or proxy URLs. Send only public marketplace targets. For Reddit Requests, never send Reddit cookies, account credentials, session tokens, private community content, or proxy URLs. Send only public Reddit targets, public community profiles, and public search filters. For LinkedIn Requests, never send LinkedIn cookies, account credentials, session tokens, private profile content, mailbox credentials, OTP codes, or proxy URLs. Send only public LinkedIn targets and public search filters. For Instagram Requests, never send Instagram cookies, account credentials, session tokens, private profile content, or proxy URLs. Send only public Instagram targets. ## Prices `GET /v1/data-sources` returns `priceEvents` in USD micro-units. `1,000,000` means `$1.00`. Prices are per public Record unit, such as `place`, `post`, `review`, `page`, or `record`.