Plan costs as the workload changes
cost_scenariosRead-onlyIdempotent
Use this when: the user asks how the cost changes as the workload grows or shifts, or at what volume another plan becomes the cheapest. Do not use this when: the workload is fixed (use search). Show how web data API plan costs change when the monthly workload changes, for example twice the pages or a larger share of JavaScript pages. Along the path from the current to a target workload it returns the cheapest fully matching plan at both ends, each workload where the cheapest plan changes, and for tracked plans where the cost first steps up, where the plan can no longer cover the volume and where the budget is exceeded. Costs follow published pricing rules (whole packs of extra credits, per-period pack limits, per-connection browser billing, monthly minimums) with official source sentences.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| scale | No | Multiply every monthly count by this factor for the end of the path, e.g. 2 for twice the current workload. Give target or scale. | |
| detail | No | summary returns one source sentence per fact; full returns every recorded fact and sentence. | summary |
| target | No | Workload at the end of the path; fields not given keep their current value. Give target or scale. | |
| offer_ids | No | Compare only these plans and follow each of them along the path. Default: every plan that can serve the workload, following the cheapest full match at the start. | |
| preferred | No | Nice-to-have conditions; they do not filter, they break ties. | |
| data_regions | No | Regions where data must be stored or processed, e.g. ["EU"]. Different from exit-IP countries. | |
| billing_types | No | Acceptable billing: monthly_subscription (A plan with a fixed fee (or minimum commitment) billed every month.) annual_subscription (A plan paid for a year at a time.) pay_as_you_go (No plan fee; a price per unit of use, billed after use or drawn from a balance topped up with any amount.) prepaid_credits (A fixed-size credit pack bought before use, usually with an expiry.) Free plans always qualify. | |
| monthly_pages | No | Pages per month by type: plain_html (static pages), javascript (needs rendering), premium_proxy (blocked sites that need residential/premium proxies), javascript_premium_proxy (both). | |
| product_types | No | Limit to these product types. Default: every type that can serve the workload. | |
| search_engines | No | Search engines whose results the plan must return, each at the plan's search price: google, bing, yahoo, yandex, baidu, duckduckgo, naver, brave (brave is Brave's own index). monthly_searches is the total over all of them. | |
| min_concurrency | No | Minimum number of concurrent requests (or browsers) the plan must allow. | |
| monthly_searches | No | Search requests per month (one results page each). | |
| search_countries | No | ISO 3166-1 alpha-2 codes of the countries whose search results the searches must return (the search engine's country setting, e.g. Google gl), e.g. ["GB","CA"]. Different from exit_ip_countries. | |
| exit_ip_countries | No | ISO 3166-1 alpha-2 codes of countries the page requests must exit from, e.g. ["US","DE"]. For search results of a country use search_countries. | |
| ai_extraction_pages | No | How many of the pages need their fields extracted by an AI model (from a prompt or a schema, or automatically) without writing selectors. Each page counts in one of the two extraction fields. | |
| min_pages_per_crawl | No | Pages one crawl job (from one start URL, following links) must be able to reach. A plan whose crawl has no page cap meets any number; give the size of the largest site to crawl. Different from the monthly page total. | |
| monthly_pages_total | No | Total pages per month when the split by type is not known yet. Costs and verdicts then cover every share of JavaScript-rendered pages from 0% to 100% of the total (no premium proxies), and the result lists monthly_pages under needs_input. | |
| search_result_types | No | Result types the parsed search response must contain: organic, ads, local_pack, knowledge_graph, people_also_ask, related_searches, shopping, news, images, videos, ai_overview. | |
| max_monthly_cost_usd | No | Monthly budget in USD before tax. Compared with listed prices; annual plans use their per-month equivalent. | |
| min_requests_per_minute | No | Minimum request rate the plan must allow, per minute. | |
| browser_seconds_per_page | No | Browser time per page in seconds, for headless-browser products billed by time. Every plan must then serve pages that take this long: a hosted browser does, a request-based API only when one request may run that long. | |
| realtime_search_required | No | Search results must be returned in real time (not through a queue). | |
| target_errors_not_billed | No | Error responses from the target site (e.g. 404) must not be billed. | |
| needs_recurring_free_tier | No | The plan must be usable every month without paying (a free plan with a monthly allowance or a monthly free credit). | |
| failed_requests_not_billed | No | Requests that fail on the provider side (timeouts, blocks, 5xx) must not be billed. A flat monthly price for unlimited requests meets it, since no request is billed on its own; when only success-based billing will do, use only_successful_requests_billed. | |
| structured_extraction_pages | No | How many of the pages must come back as JSON fields rather than HTML or text, by any method the plan offers (CSS or XPath selectors, a schema, or AI). When the fields must be found without writing selectors, use ai_extraction_pages instead; each page counts in one of the two. | |
| only_successful_requests_billed | No | Billing must count successful requests only: each successful request is charged (or draws credits) and failed ones cost nothing. A flat monthly price for unlimited requests does not meet it, since the price is the same whatever succeeds. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| as_of | Yes | ||
| notes | Yes | ||
| plans | Yes | Every plan named above, with the official facts its costs were computed from. | |
| at_end | Yes | Up to three cheapest full matches at the target workload. | |
| counts | Yes | ||
| request | No | ||
| tracked | Yes | ||
| at_start | Yes | Up to three cheapest full matches at the current workload. | |
| compared | Yes | ||
| switches | Yes | Each workload on the path where the cheapest full match changes. | |
| assumptions | Yes | ||
| needs_input | Yes |