{"sources":[{"id":"web","name":"Web","summary":"Search the web and read any public page as markdown, HTML, links, a screenshot or JSON","kind":"site"},{"id":"browser","name":"browser","summary":"browser","kind":"site"},{"id":"webhook","name":"webhook","summary":"webhook","kind":"site"}],"endpoints":[{"id":"search","title":"Search","summary":"Search the web, news, images, scholarly papers, companies, people and government documents in one call","bestWhen":"Best when you want web results, news, images or all three at once, grouped by type, with the page text of the top web results if you ask for it. Send categories research for scholarly papers with authors, venue and citation counts, companies for company profiles filtered by place, industry, size and founding year, people for people by role, company, place or research topic, developer for passages from GitHub issues, pull requests, releases, READMEs, developer docs and API operations, gov for statutes, regulations, register notices and bills, or videos for passages from what is said in YouTube videos shared under a Creative Commons license, with the channel credited.","method":"POST","path":"/v1/search","credits":2,"maxCredits":4670,"pricing":"2 credits per 10 results from each source and each research, companies, people, developer, gov or videos list, plus 1 credit for each web or news result that comes back with its page text when scrapeOptions has formats, and 4 more for each summary or json with a schema or prompt that returns something","keyless":true,"cacheTtlSeconds":0,"input":{"type":"object","properties":{"query":{"description":"What to search for, up to 500 characters. Search operators work in web results: quotes for an exact phrase, -word, site:, -site:, filetype:, inurl:, allinurl:, intitle: and allintitle:. In image results, imagesize:WIDTHxHEIGHT keeps images of exactly that size and larger:WIDTHxHEIGHT keeps images at least that large.","type":"string","minLength":1,"maxLength":500},"sources":{"description":"What to search: web, news, images. Each is a string or {type}. Default web, or none when categories asks for research, companies, people, developer, gov or videos.","minItems":1,"maxItems":5,"type":"array","items":{"anyOf":[{"type":"string","enum":["web","news","images"]},{"type":"object","properties":{"type":{"type":"string","const":"web"},"tbs":{"type":"string"},"location":{"type":"string"},"country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 country code, e.g. us. Any case is accepted."},"lang":{"description":"Two-letter language for web results, like de. It steers which pages come back; some results can still be in other languages.","type":"string","pattern":"^[A-Za-z]{2}$"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["news","images"]}},"required":["type"],"additionalProperties":false}]}},"categories":{"description":"pdf: web results that are PDF files. research: scholarly papers, in a research list, ranked by relevance then citations. companies: companies that match the query, in a companies list, best matches first. The query can name a place, industry, employee count, founding year and funding stage, like fintech startups in Berlin, 50-200 employees. people: people that match the query, in a people list, best matches first. The query can name a role, company, place or research topic, like CFO of Stripe, founders of fintech startups in Berlin, or researchers on CRISPR base editing. Each person has roles, affiliations and public profile links, never contact details. developer: passages from GitHub READMEs, issues, merged pull requests, releases, developer docs and API operations, in a developer list; send it as an object to filter by repos, types, language and minStars. gov: statutes, regulations, register notices and bills from government sources, in the web group with category gov and the kind, jurisdiction and citation of each. videos: passages from what is said in YouTube videos shared under a Creative Commons license, in a videos list, one result per video, with the channel, the license and the watch link; the link carries &t= only when the passage's start is exact. The index is a June 2024 snapshot of English videos, so a link may be dead.","type":"array","items":{"anyOf":[{"type":"string","enum":["developer","gov","research","pdf","companies","people","videos"]},{"type":"object","properties":{"type":{"type":"string","enum":["developer","gov","research","pdf","companies","people","videos"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"developer"},"repos":{"default":[],"description":"Only results from these GitHub repositories, as owner/name.","maxItems":5,"type":"array","items":{"type":"string","pattern":"^[\\w.-]+\\/[\\w.-]+$"}},"types":{"default":[],"description":"Only these result types: readme, issue, pull_request, release, operation, doc.","type":"array","items":{"type":"string","enum":["readme","issue","pull_request","release","operation","doc"]}},"language":{"description":"Only repositories whose main language is this, like TypeScript.","type":"string","minLength":1},"minStars":{"description":"Only repositories with at least this many GitHub stars.","type":"integer","minimum":0,"maximum":9007199254740991}},"required":["type"],"additionalProperties":false}]}},"maxAge":{"description":"Accept a stored answer up to this many milliseconds old, at most 30 days. Without it, 15 minutes for news and 1 hour for web and images. 0 always searches live.","type":"integer","minimum":0,"maximum":9007199254740991},"limit":{"description":"Most results to return for each source. Default 10, or 5 when scrapeOptions has formats, which reads every web and news result returned. News returns at most 50.","type":"integer","minimum":1,"maximum":100},"tbs":{"description":"Time filter: qdr:d, qdr:w, qdr:m or qdr:y, or cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY, plus sbd:1, like sbd:1,qdr:w. sbd:1 sorts newest first; results without a date come last. Web takes all of them; news takes qdr and sbd; images take none.","type":"string","minLength":1},"location":{"description":"Where to search from, like Germany or San Francisco,California,United States. The last part is the country and replaces country. A city before it narrows web results to that place.","type":"string","minLength":1},"country":{"description":"Two-letter country to search from, like us. uk is read as gb. Image results are always US.","type":"string","pattern":"^[A-Za-z]{2}$"},"lang":{"description":"Two-letter language for web results, like de. It steers which pages come back; some results can still be in other languages.","type":"string","pattern":"^[A-Za-z]{2}$"},"includeDomains":{"maxItems":10,"type":"array","items":{"type":"string"}},"excludeDomains":{"maxItems":10,"type":"array","items":{"type":"string"}},"safe":{"description":"Hide explicit web, news and image results when true.","type":"boolean"},"timeout":{"description":"Milliseconds to wait for the sources, from 1,000 to 120,000; more is read as 120,000. Default 60,000. A source that has not answered by then is left out with a warning. When none has, the call fails and costs nothing.","default":60000,"type":"integer","minimum":1000,"maximum":9007199254740991},"ignoreInvalidURLs":{"default":false,"description":"Leave out results whose address cannot be read as a page.","type":"boolean"},"highlights":{"default":true,"description":"On by default. Adds highlights to a web result when its page can be read quickly: the passages that best match the query, up to about 2,000 characters for the first 3 results and one passage for the rest. description stays the search engine's snippet; a result without one gets the start of its best passage. Send false to leave highlights out.","type":"boolean"},"scrapeOptions":{"description":"With formats, reads each web and news result, as many as limit asks for, within timeout, and puts the passages that best match the query in each web result's highlights. Without formats no page is read and nothing more is charged. Takes the options of scrape: formats (markdown, html, rawHtml, links, images, summary, screenshot, json and the rest), onlyMainContent, includeTags, excludeTags, maxAge, minAge, waitFor, mobile, timeout (per page), headers, actions, location, parsers, profile and zeroDataRetention. Costs what scrape costs for each page read: 1 credit, plus 4 for each summary or json with a schema or prompt that returns something.","type":"object","properties":{"formats":{"description":"What to return: markdown (clean page text), summary (a short summary of the page), html (the cleaned page), rawHtml (the page as sent), audio and video (for a YouTube link: the audio track as an M4A file, or the video as an MP4 file, as a link that works for 1 hour), rawBase64 (the bytes the site sent, Base64 encoded, from a live read; metadata.contentType says what they are), links (every link on the page), images (every image address), screenshot (a link to a JPEG of the visible page, kept for 7 days), changeTracking (what changed in the markdown since your key last read this page with the same options, kept 30 days; add modes [\"git-diff\",\"json\"] with a schema or prompt to compare fields too), question (send { \"type\": \"question\", \"question\": \"...\" } to get answer, null when the page does not state one), product (title, brand, category, url, description and variants with price, sale, availability and images, or null) and menu (merchant, currency and sections of items with prices, or null) network (the JSON the page loaded while it rendered, up to 30 responses) and branding (the page's colors, fonts, typography, spacing, button and input styles, logo and brand images, read from how the page looks, with a field left out when the page does not show it). Send { \"type\": \"screenshot\", \"fullPage\": true } for the whole page. Send { \"type\": \"highlights\", \"query\": \"refund policy\" } for the passages that best match a query. Send { \"type\": \"json\", \"schema\": { \"type\": \"object\", \"properties\": { \"price\": { \"type\": \"number\" } } } } or { \"type\": \"json\", \"prompt\": \"the price and the stock\" } for fields filled from the page, each checked against it. Send { \"type\": \"json\", \"parser\": \"amazon-product\" } to get a site's own data as json instead of reading the page; GET /v1/parsers lists the parsers. Send { \"type\": \"json\", \"rules\": { \"title\": \"h1\", \"links\": { \"selector\": \"a\", \"type\": \"list\", \"output\": \"@href\" } } } to read the page with CSS rules and no model, at the page's own price. Send { \"type\": \"attributes\", \"selectors\": [{ \"selector\": \"a\", \"attribute\": \"href\" }] } for attribute values, returned in attributes. Without a parser or rules, json needs a schema or a prompt and is filled from the page. json with a schema or a prompt, summary, highlights, question, product, menu and changeTracking in json mode cost 4 credits more each when they return something. json with rules or a parser, and attributes, cost nothing more. A screenshot, network or branding read costs 1 credit, the same as any page. A PDF comes back as markdown only, and costs 1 credit more for each page of text that comes back. A CSV or an Excel .xlsx file comes back as markdown tables.","default":["markdown"],"minItems":1,"maxItems":20,"type":"array","items":{"anyOf":[{"type":"string","enum":["markdown","summary","html","rawHtml","rawBase64","links","images","network","branding","audio","video","screenshot","changeTracking","product","menu"]},{"type":"object","properties":{"type":{"type":"string","enum":["markdown","summary","html","rawHtml","rawBase64","links","images","network","branding","audio","video"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"changeTracking"},"modes":{"description":"git-diff returns a unified diff of the markdown. json compares the fields in schema or prompt between this read and the last one. Without modes you get git-diff.","maxItems":2,"type":"array","items":{"type":"string","enum":["git-diff","json"]}},"schema":{"description":"The fields to fill, as a JSON Schema (draft-07 or 2020-12) object with properties. Pydantic's model_json_schema() and zod's toJSONSchema() output work as they are. enum, const, anyOf, oneOf, nullable types, $ref with $defs, required, descriptions and any key names are read. Up to 100 top-level fields and 32 KB. A field the page does not state comes back null.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"prompt":{"description":"With json mode: what to compare, in plain words, such as the price and stock.","type":"string","minLength":1,"maxLength":10000},"tag":{"type":"null"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"question"},"question":{"type":"string","minLength":1,"maxLength":10000,"description":"A question to answer from the page, such as what the refund window is."}},"required":["type","question"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"product"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"menu"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"screenshot"},"fullPage":{"default":false,"description":"Capture the whole page from top to bottom instead of the visible part.","type":"boolean"},"quality":{"description":"JPEG quality from 1 to 100. The default is 70.","type":"integer","minimum":1,"maximum":100},"viewport":{"description":"The window size in pixels, such as { width: 390, height: 844 }.","type":"object","properties":{"width":{"type":"integer","minimum":200,"maximum":3840},"height":{"type":"integer","minimum":200,"maximum":2160}},"required":["width","height"],"additionalProperties":false}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"highlights"},"query":{"type":"string","minLength":1,"maxLength":10000,"description":"What you are looking for on the page, such as refund policy."},"count":{"default":5,"description":"How many passages to return, best match first.","type":"integer","minimum":1,"maximum":20}},"required":["type","query"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"json"},"parser":{"description":"Read the page with a named parser, which gives the site's own data as json. The url must be the kind of page the parser reads. Parsers are the only way to read some sites. GET /v1/parsers lists them.","type":"string"},"options":{"description":"Only with parser: extra inputs for it, such as { \"page\": 2 } for the next page of results or { \"minRating\": 4.5 } for a filter. GET /v1/parsers lists what each parser accepts.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema1"}},"schema":{"description":"The fields to fill, as a JSON Schema (draft-07 or 2020-12) object with properties. Pydantic's model_json_schema() and zod's toJSONSchema() output work as they are. enum, const, anyOf, oneOf, nullable types, $ref with $defs, required, descriptions and any key names are read. Up to 100 top-level fields and 32 KB. A field the page does not state comes back null.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"prompt":{"description":"What to pull from the page in plain words, such as the version and the release date.","type":"string","minLength":1,"maxLength":10000},"rules":{"description":"Read the page with CSS rules instead of a model, no extra fee. Each field is a selector such as \"h1\" (the first match's text), \"a@href\" (an attribute) or { \"selector\": \"li\", \"type\": \"list\", \"output\": \"text\" | \"html\" | \"@attribute\" | { nested fields } }. A missing item is null and an unmatched list is []. Relative links become absolute. Up to 100 fields, 5 levels deep. Not with schema, prompt or parser.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema2"}},"checkPromptInjection":{"description":"Deprecated: send checkPromptInjection at the top level of the call.","type":"boolean"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"attributes"},"selectors":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"selector":{"type":"string","minLength":1},"attribute":{"type":"string","minLength":1,"maxLength":100}},"required":["selector","attribute"],"additionalProperties":false},"description":"The elements and attributes to read, such as { selector: 'a.buy', attribute: 'href' }."}},"required":["type","selectors"],"additionalProperties":false}]}},"onlyMainContent":{"default":true,"description":"Keep only the page's main content, without menus, headers, footers and ads.","type":"boolean"},"onlyCleanContent":{"description":"Send true to have a model remove what onlyMainContent leaves behind in the markdown: cookie banners, ads, share widgets, breadcrumbs, sign-up prompts, comment prompts and related-article lists. It only removes whole paragraphs and lists; it never rewrites or adds text, and code blocks are always kept. Skipped with a warning when the page is too long to clean or the model does not answer. Not with zeroDataRetention. Summary, answers and highlights are made from the cleaned markdown.","type":"boolean"},"includeTags":{"description":"Keep only the parts of the page that match these CSS selectors, such as article or .price. When set, onlyMainContent is not applied.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"excludeTags":{"description":"Remove the parts of the page that match these CSS selectors, such as .comments.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"maxAge":{"description":"Accept a stored answer up to this many milliseconds old, at most 30 days. Without it, 2 days, or less for a site whose pages change often, and a copy up to twice that age (at most 7 days) comes back at once as stale while a fresh read runs. 0 always reads the page live. metadata.cacheState says which one you got.","type":"integer","minimum":0,"maximum":9007199254740991},"minAge":{"description":"Answer only from a stored copy that is at least this many milliseconds old, and never read the page live. 0 accepts any stored copy. A page with no such copy is notFound.","type":"integer","minimum":0,"maximum":9007199254740991},"headers":{"description":"Extra request headers to send to the site, such as { \"x-plan\": \"pro\" }. A read with headers is never answered from or saved to a stored copy.","type":"object","propertyNames":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$"},"additionalProperties":{"type":"string","maxLength":2000,"pattern":"^[\\t\\x20-\\x7e]*$"}},"waitFor":{"description":"Extra milliseconds to wait before reading, up to 60000, for pages that load their content late. To wait for an element, add a wait action with a selector. A read that waits costs 1 credit, the same as any page.","type":"integer","minimum":0,"maximum":60000},"mobile":{"description":"Read the page as a phone would: a phone-sized screen and the mobile version of the site. The page loads in a browser.","type":"boolean"},"skipTlsVerification":{"description":"Send true to read a page whose certificate is expired, self-signed or for another name. The read is not private against someone between us and the site.","type":"boolean"},"timeout":{"default":30000,"description":"How long to keep trying, in milliseconds, from 1 second to 5 minutes; 30 seconds by default. A page that needs a browser needs at least 5 seconds, and pages behind a bot check can need 10 to 30 seconds the first time. A read that runs out of time is an error and costs nothing.","type":"integer","minimum":1000,"maximum":300000},"parsers":{"description":"Only the pdf parser exists. Send \"pdf\" or { \"type\": \"pdf\", mode, maxPages, pages, blocks, pageMarkers } with the same meaning as in parse. Without mode a PDF is read as auto: from its text layer, and from the picture of any page that has no text. fast reads the text layer only, and ocr reads the picture of every page, up to 20 pages. Each page of text that comes back costs 1 credit. Pictures are read only with an API key.","minItems":1,"type":"array","items":{"anyOf":[{"type":"string","const":"pdf"},{"type":"object","properties":{"type":{"type":"string","const":"pdf"},"mode":{"description":"fast reads the text layer only. auto (the default) reads the text layer and reads the picture of any page that has none. ocr reads the picture of every page.","type":"string","enum":["fast","auto","ocr"]},"maxPages":{"description":"Read at most this many pages, up to 500, which is also the default.","type":"integer","minimum":1,"maximum":500},"pages":{"description":"Send true to also get each page's markdown in pages, as { pageNumber, markdown }. No extra charge.","type":"boolean"},"blocks":{"description":"Send true to also get the page's layout in blocks: each title, section header or run of text, with its page, reading order, position on the page (bbox as left, top, right, bottom from 0 to 1) and where its text sits in that page's markdown (span, as in pages). Tables, figures and formulas are not told apart. A page read from its picture is one block. No extra charge.","type":"boolean"},"pageMarkers":{"description":"Send true to mark page breaks in the markdown: pages are joined with \"---\" and a <!-- page N --> line, where N is the page that follows. No extra charge.","type":"boolean"}},"required":["type"],"additionalProperties":false}]}},"actions":{"description":"Up to 50 steps to run on the page, in order, before reading it: { \"type\": \"wait\", \"milliseconds\": 500 } (up to 60 seconds), { \"type\": \"wait\", \"selector\": \".results\" }, { \"type\": \"click\", \"selector\": \"button.more\" }, { \"type\": \"write\", \"text\": \"tides\" }, { \"type\": \"press\", \"key\": \"Enter\" }, { \"type\": \"scroll\", \"direction\": \"down\" } (also up, left or right; amount is pixels, \"viewport\" or \"max\"; maxScrolls 1 to 50; selector scrolls an inner container; \"max\" keeps scrolling until the page stops growing, for feeds that load as you go), { \"type\": \"screenshot\", \"fullPage\": true } (links come back in actions.screenshots), { \"type\": \"scrape\" } (the page at that point, in actions.scrapes), { \"type\": \"executeJavascript\", \"script\": \"document.title\" } (results in actions.javascriptReturns), { \"type\": \"pdf\", \"format\": \"A4\" } (links in actions.pdfs) or { \"type\": \"perform\", \"action\": \"Click the Load more button\" } (a step in plain words, up to 5 browser steps on this page, never leaving the site; at most 5 per call). A read with actions costs 1 credit, the same as any page; the actions themselves add nothing. If an action fails, you still get the page as it stood, with a warning that names the action and says why.","minItems":1,"maxItems":50,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"wait"},"milliseconds":{"type":"integer","minimum":1,"maximum":60000}},"required":["type","milliseconds"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"wait"},"selector":{"type":"string","minLength":1}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"click"},"selector":{"type":"string","minLength":1},"all":{"type":"boolean","const":false}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"write"},"text":{"type":"string","minLength":1}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"press"},"key":{"type":"string","minLength":1,"maxLength":40}},"required":["type","key"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scroll"},"direction":{"default":"down","type":"string","enum":["up","down","left","right"]},"amount":{"anyOf":[{"type":"integer","minimum":1,"maximum":100000},{"type":"string","enum":["viewport","max"]}]},"maxScrolls":{"type":"integer","minimum":1,"maximum":50},"selector":{"type":"string","minLength":1}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"screenshot"},"fullPage":{"type":"boolean"},"quality":{"type":"integer","minimum":1,"maximum":100},"viewport":{"type":"object","properties":{"width":{"type":"integer","minimum":200,"maximum":3840},"height":{"type":"integer","minimum":200,"maximum":2160}},"required":["width","height"],"additionalProperties":false}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scrape"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"executeJavascript"},"script":{"type":"string","minLength":1,"maxLength":20000}},"required":["type","script"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"pdf"},"format":{"type":"string","enum":["Letter","Legal","Tabloid","Ledger","A0","A1","A2","A3","A4","A5","A6"]},"landscape":{"type":"boolean"},"scale":{"type":"number","minimum":0.1,"maximum":2}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"perform"},"action":{"type":"string","minLength":1,"maxLength":500}},"required":["type","action"],"additionalProperties":false}]}},"location":{"description":"Where to read the page from. The default is the United States.","type":"object","properties":{"country":{"description":"Two-letter country code to read the page from, such as DE or JP.","type":"string"},"languages":{"description":"Languages to ask the site for, best first, such as [\"de\", \"en\"]. Sent as Accept-Language. A read with languages is never answered from or saved to a stored copy.","minItems":1,"maxItems":5,"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"}}},"additionalProperties":false},"removeBase64Images":{"description":"Images inside the page that carry their data in the address (data:image) are dropped by default. Send false to keep them in markdown and html.","type":"boolean"},"blockAds":{"description":"Ads and trackers are not loaded when a page runs in a browser. Send false to load them.","type":"boolean"},"fastMode":{"description":"Send true to read the page without opening a browser: the answer comes sooner, but a page that needs a browser, or that refuses a plain request, comes back as an error instead of being retried. Ignored when the call needs a browser (actions, screenshot, waitFor, mobile, profile, network, branding).","type":"boolean"},"proxy":{"description":"auto: basic first, enhanced once if the site refuses. basic: one plain attempt. enhanced: the stronger read from the start. stealth is the same as enhanced. Same price.","type":"string","enum":["auto","basic","enhanced","stealth"]},"storeInCache":{"default":true,"description":"Send false to neither read nor keep a stored copy of this page.","type":"boolean"},"lockdown":{"description":"Send true to answer only from a stored copy of the page and never read it live, whatever its age. A page with no stored copy is notFound. The same as minAge 0.","type":"boolean"},"checkPromptInjection":{"description":"Send true to scan the page text for instructions aimed at an AI model before anything is built from it. A page that has them is refused with 403 promptInjectionDetected and costs nothing. The scan adds 4 credits when it runs; a page it cannot scan fully comes back with a warning and no charge.","type":"boolean"},"redactPII":{"description":"Send true, or an object, to hide personal data in the markdown and in everything made from it (summary, answers, highlights, json). Links, html and rawHtml are not changed. A page the model cannot scan is refused rather than returned unredacted.","anyOf":[{"type":"boolean"},{"type":"object","properties":{"mode":{"default":"accurate","description":"accurate finds names and places with the model and the rest by pattern. aggressive adds guesses that catch more and may hide a little too much. fast uses patterns only, so it finds no ordinary names or places.","type":"string","enum":["accurate","aggressive","fast"]},"entities":{"default":["PERSON","EMAIL","PHONE","LOCATION","FINANCIAL","SECRET"],"description":"What to hide: PERSON, EMAIL, PHONE, LOCATION, FINANCIAL, SECRET. All by default.","minItems":1,"type":"array","items":{"type":"string","enum":["PERSON","EMAIL","PHONE","LOCATION","FINANCIAL","SECRET"]}},"replaceStyle":{"default":"tag","description":"tag writes <EMAIL>, mask writes * for each character, remove deletes it.","type":"string","enum":["tag","mask","remove"]}},"additionalProperties":false,"description":"Options for redactPII."}]},"profile":{"description":"Read the page with the cookies and local storage that earlier calls saved under this name, kept for your account for 30 days after the last use. A call with a profile always loads the page in a browser, costs 1 credit, the same as any page, and is never answered from a stored copy. Only one call at a time can save to a profile.","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128,"description":"A name you choose, such as shop-login. Calls with the same name share state."},"saveChanges":{"default":true,"description":"Keep the cookies and local storage this read leaves behind for the next call with this name. Send false to read with the profile without changing it.","type":"boolean"}},"required":["name"],"additionalProperties":false},"zeroDataRetention":{"default":false,"description":"Send true to keep nothing from this call: no stored copy is read or made, and nothing from it is logged. Costs 1 credit more per page. Not with a screenshot.","type":"boolean"}},"additionalProperties":false}},"required":["query"],"$defs":{"__schema0":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema0"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}}]},"__schema1":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema1"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema1"}}]},"__schema2":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema2"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema2"}}]}},"additionalProperties":false},"example":{"query":"nvidia earnings","sources":["web","news"],"limit":5}},{"id":"scrape","title":"Web Scrape","summary":"Scrape any public web page as markdown, HTML, links, a screenshot or JSON","bestWhen":"Best for reading a page as markdown, HTML, links or a screenshot. The page runs its JavaScript before it is read. Without formats you get markdown. Send formats as names, [\"markdown\",\"links\"], or as objects, [{\"type\":\"screenshot\",\"fullPage\":true}], or mix them. For a site's own structured data (video, social, places, shopping, jobs, homes) send formats [{\"type\":\"json\",\"parser\":\"<name>\"}]; GET /v1/parsers lists the parsers. A YouTube video link comes back as its title, channel, date, length, views, likes and description. A CSV or Excel .xlsx file comes back as markdown tables. To read less, send query (what you look for) and get only the matching passages in page order, or maxChars with offset to read a long page, PDF or file part by part: each answer names nextOffset while text remains.","method":"POST","path":"/v1/scrape","credits":1,"maxCredits":30,"pricing":"1 credit for any page, however it is reached. checkPromptInjection adds 4 credits when the scan runs, json with a schema or a prompt, summary, highlights, question, product, menu and changeTracking in json mode add 4 credits each when they return something. CSS rules and attributes add nothing. A PDF adds 1 credit for each page of text that comes back, so a PDF read with maxChars, offset or query is charged for the share of its pages that it returns, at least 1 page. Browser actions add nothing. An answer from a stored copy within maxAge costs 1 credit like any page. A page that comes back with a 404 or 410 status, or cannot be read, costs nothing. creditsUsed shows what the call cost","keyless":true,"cacheTtlSeconds":0,"input":{"type":"object","properties":{"url":{"description":"The page or PDF to read, such as https://bun.com/docs.","type":"string"},"formats":{"description":"What to return: markdown (clean page text), summary (a short summary of the page), html (the cleaned page), rawHtml (the page as sent), audio and video (for a YouTube link: the audio track as an M4A file, or the video as an MP4 file, as a link that works for 1 hour), rawBase64 (the bytes the site sent, Base64 encoded, from a live read; metadata.contentType says what they are), links (every link on the page), images (every image address), screenshot (a link to a JPEG of the visible page, kept for 7 days), changeTracking (what changed in the markdown since your key last read this page with the same options, kept 30 days; add modes [\"git-diff\",\"json\"] with a schema or prompt to compare fields too), question (send { \"type\": \"question\", \"question\": \"...\" } to get answer, null when the page does not state one), product (title, brand, category, url, description and variants with price, sale, availability and images, or null) and menu (merchant, currency and sections of items with prices, or null) network (the JSON the page loaded while it rendered, up to 30 responses) and branding (the page's colors, fonts, typography, spacing, button and input styles, logo and brand images, read from how the page looks, with a field left out when the page does not show it). Send { \"type\": \"screenshot\", \"fullPage\": true } for the whole page. Send { \"type\": \"highlights\", \"query\": \"refund policy\" } for the passages that best match a query. Send { \"type\": \"json\", \"schema\": { \"type\": \"object\", \"properties\": { \"price\": { \"type\": \"number\" } } } } or { \"type\": \"json\", \"prompt\": \"the price and the stock\" } for fields filled from the page, each checked against it. Send { \"type\": \"json\", \"parser\": \"amazon-product\" } to get a site's own data as json instead of reading the page; GET /v1/parsers lists the parsers. Send { \"type\": \"json\", \"rules\": { \"title\": \"h1\", \"links\": { \"selector\": \"a\", \"type\": \"list\", \"output\": \"@href\" } } } to read the page with CSS rules and no model, at the page's own price. Send { \"type\": \"attributes\", \"selectors\": [{ \"selector\": \"a\", \"attribute\": \"href\" }] } for attribute values, returned in attributes. Without a parser or rules, json needs a schema or a prompt and is filled from the page. json with a schema or a prompt, summary, highlights, question, product, menu and changeTracking in json mode cost 4 credits more each when they return something. json with rules or a parser, and attributes, cost nothing more. A screenshot, network or branding read costs 1 credit, the same as any page. A PDF comes back as markdown only, and costs 1 credit more for each page of text that comes back. A CSV or an Excel .xlsx file comes back as markdown tables.","default":["markdown"],"minItems":1,"maxItems":20,"type":"array","items":{"anyOf":[{"type":"string","enum":["markdown","summary","html","rawHtml","rawBase64","links","images","network","branding","audio","video","screenshot","changeTracking","product","menu"]},{"type":"object","properties":{"type":{"type":"string","enum":["markdown","summary","html","rawHtml","rawBase64","links","images","network","branding","audio","video"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"changeTracking"},"modes":{"description":"git-diff returns a unified diff of the markdown. json compares the fields in schema or prompt between this read and the last one. Without modes you get git-diff.","maxItems":2,"type":"array","items":{"type":"string","enum":["git-diff","json"]}},"schema":{"description":"The fields to fill, as a JSON Schema (draft-07 or 2020-12) object with properties. Pydantic's model_json_schema() and zod's toJSONSchema() output work as they are. enum, const, anyOf, oneOf, nullable types, $ref with $defs, required, descriptions and any key names are read. Up to 100 top-level fields and 32 KB. A field the page does not state comes back null.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"prompt":{"description":"With json mode: what to compare, in plain words, such as the price and stock.","type":"string","minLength":1,"maxLength":10000},"tag":{"type":"null"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"question"},"question":{"type":"string","minLength":1,"maxLength":10000,"description":"A question to answer from the page, such as what the refund window is."}},"required":["type","question"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"product"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"menu"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"screenshot"},"fullPage":{"default":false,"description":"Capture the whole page from top to bottom instead of the visible part.","type":"boolean"},"quality":{"description":"JPEG quality from 1 to 100. The default is 70.","type":"integer","minimum":1,"maximum":100},"viewport":{"description":"The window size in pixels, such as { width: 390, height: 844 }.","type":"object","properties":{"width":{"type":"integer","minimum":200,"maximum":3840},"height":{"type":"integer","minimum":200,"maximum":2160}},"required":["width","height"],"additionalProperties":false}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"highlights"},"query":{"type":"string","minLength":1,"maxLength":10000,"description":"What you are looking for on the page, such as refund policy."},"count":{"default":5,"description":"How many passages to return, best match first.","type":"integer","minimum":1,"maximum":20}},"required":["type","query"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"json"},"parser":{"description":"Read the page with a named parser, which gives the site's own data as json. The url must be the kind of page the parser reads. Parsers are the only way to read some sites. GET /v1/parsers lists them.","type":"string"},"options":{"description":"Only with parser: extra inputs for it, such as { \"page\": 2 } for the next page of results or { \"minRating\": 4.5 } for a filter. GET /v1/parsers lists what each parser accepts.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema1"}},"schema":{"description":"The fields to fill, as a JSON Schema (draft-07 or 2020-12) object with properties. Pydantic's model_json_schema() and zod's toJSONSchema() output work as they are. enum, const, anyOf, oneOf, nullable types, $ref with $defs, required, descriptions and any key names are read. Up to 100 top-level fields and 32 KB. A field the page does not state comes back null.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"prompt":{"description":"What to pull from the page in plain words, such as the version and the release date.","type":"string","minLength":1,"maxLength":10000},"rules":{"description":"Read the page with CSS rules instead of a model, no extra fee. Each field is a selector such as \"h1\" (the first match's text), \"a@href\" (an attribute) or { \"selector\": \"li\", \"type\": \"list\", \"output\": \"text\" | \"html\" | \"@attribute\" | { nested fields } }. A missing item is null and an unmatched list is []. Relative links become absolute. Up to 100 fields, 5 levels deep. Not with schema, prompt or parser.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema2"}},"checkPromptInjection":{"description":"Deprecated: send checkPromptInjection at the top level of the call.","type":"boolean"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"attributes"},"selectors":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"selector":{"type":"string","minLength":1},"attribute":{"type":"string","minLength":1,"maxLength":100}},"required":["selector","attribute"],"additionalProperties":false},"description":"The elements and attributes to read, such as { selector: 'a.buy', attribute: 'href' }."}},"required":["type","selectors"],"additionalProperties":false}]}},"onlyMainContent":{"default":true,"description":"Keep only the page's main content, without menus, headers, footers and ads.","type":"boolean"},"onlyCleanContent":{"description":"Send true to have a model remove what onlyMainContent leaves behind in the markdown: cookie banners, ads, share widgets, breadcrumbs, sign-up prompts, comment prompts and related-article lists. It only removes whole paragraphs and lists; it never rewrites or adds text, and code blocks are always kept. Skipped with a warning when the page is too long to clean or the model does not answer. Not with zeroDataRetention. Summary, answers and highlights are made from the cleaned markdown.","type":"boolean"},"includeTags":{"description":"Keep only the parts of the page that match these CSS selectors, such as article or .price. When set, onlyMainContent is not applied.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"excludeTags":{"description":"Remove the parts of the page that match these CSS selectors, such as .comments.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"maxAge":{"description":"Accept a stored answer up to this many milliseconds old, at most 30 days. Without it, 2 days, or less for a site whose pages change often, and a copy up to twice that age (at most 7 days) comes back at once as stale while a fresh read runs. 0 always reads the page live. metadata.cacheState says which one you got.","type":"integer","minimum":0,"maximum":9007199254740991},"minAge":{"description":"Answer only from a stored copy that is at least this many milliseconds old, and never read the page live. 0 accepts any stored copy. A page with no such copy is notFound.","type":"integer","minimum":0,"maximum":9007199254740991},"headers":{"description":"Extra request headers to send to the site, such as { \"x-plan\": \"pro\" }. A read with headers is never answered from or saved to a stored copy.","type":"object","propertyNames":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$"},"additionalProperties":{"type":"string","maxLength":2000,"pattern":"^[\\t\\x20-\\x7e]*$"}},"waitFor":{"description":"Extra milliseconds to wait before reading, up to 60000, for pages that load their content late. To wait for an element, add a wait action with a selector. A read that waits costs 1 credit, the same as any page.","type":"integer","minimum":0,"maximum":60000},"mobile":{"description":"Read the page as a phone would: a phone-sized screen and the mobile version of the site. The page loads in a browser.","type":"boolean"},"skipTlsVerification":{"description":"Send true to read a page whose certificate is expired, self-signed or for another name. The read is not private against someone between us and the site.","type":"boolean"},"timeout":{"default":60000,"description":"How long to keep trying, in milliseconds, from 1 second to 5 minutes; 60 seconds by default. A page that needs a browser needs at least 5 seconds, and pages behind a bot check can need 10 to 30 seconds the first time. A read that runs out of time is an error and costs nothing.","type":"integer","minimum":1000,"maximum":300000},"parsers":{"description":"Only the pdf parser exists. Send \"pdf\" or { \"type\": \"pdf\", mode, maxPages, pages, blocks, pageMarkers } with the same meaning as in parse. Without mode a PDF is read as auto: from its text layer, and from the picture of any page that has no text. fast reads the text layer only, and ocr reads the picture of every page, up to 20 pages. Each page of text that comes back costs 1 credit. Pictures are read only with an API key.","minItems":1,"type":"array","items":{"anyOf":[{"type":"string","const":"pdf"},{"type":"object","properties":{"type":{"type":"string","const":"pdf"},"mode":{"description":"fast reads the text layer only. auto (the default) reads the text layer and reads the picture of any page that has none. ocr reads the picture of every page.","type":"string","enum":["fast","auto","ocr"]},"maxPages":{"description":"Read at most this many pages, up to 500, which is also the default.","type":"integer","minimum":1,"maximum":500},"pages":{"description":"Send true to also get each page's markdown in pages, as { pageNumber, markdown }. No extra charge.","type":"boolean"},"blocks":{"description":"Send true to also get the page's layout in blocks: each title, section header or run of text, with its page, reading order, position on the page (bbox as left, top, right, bottom from 0 to 1) and where its text sits in that page's markdown (span, as in pages). Tables, figures and formulas are not told apart. A page read from its picture is one block. No extra charge.","type":"boolean"},"pageMarkers":{"description":"Send true to mark page breaks in the markdown: pages are joined with \"---\" and a <!-- page N --> line, where N is the page that follows. No extra charge.","type":"boolean"}},"required":["type"],"additionalProperties":false}]}},"actions":{"description":"Up to 50 steps to run on the page, in order, before reading it: { \"type\": \"wait\", \"milliseconds\": 500 } (up to 60 seconds), { \"type\": \"wait\", \"selector\": \".results\" }, { \"type\": \"click\", \"selector\": \"button.more\" }, { \"type\": \"write\", \"text\": \"tides\" }, { \"type\": \"press\", \"key\": \"Enter\" }, { \"type\": \"scroll\", \"direction\": \"down\" } (also up, left or right; amount is pixels, \"viewport\" or \"max\"; maxScrolls 1 to 50; selector scrolls an inner container; \"max\" keeps scrolling until the page stops growing, for feeds that load as you go), { \"type\": \"screenshot\", \"fullPage\": true } (links come back in actions.screenshots), { \"type\": \"scrape\" } (the page at that point, in actions.scrapes), { \"type\": \"executeJavascript\", \"script\": \"document.title\" } (results in actions.javascriptReturns), { \"type\": \"pdf\", \"format\": \"A4\" } (links in actions.pdfs) or { \"type\": \"perform\", \"action\": \"Click the Load more button\" } (a step in plain words, up to 5 browser steps on this page, never leaving the site; at most 5 per call). A read with actions costs 1 credit, the same as any page; the actions themselves add nothing. If an action fails, you still get the page as it stood, with a warning that names the action and says why.","minItems":1,"maxItems":50,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"wait"},"milliseconds":{"type":"integer","minimum":1,"maximum":60000}},"required":["type","milliseconds"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"wait"},"selector":{"type":"string","minLength":1}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"click"},"selector":{"type":"string","minLength":1},"all":{"type":"boolean","const":false}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"write"},"text":{"type":"string","minLength":1}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"press"},"key":{"type":"string","minLength":1,"maxLength":40}},"required":["type","key"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scroll"},"direction":{"default":"down","type":"string","enum":["up","down","left","right"]},"amount":{"anyOf":[{"type":"integer","minimum":1,"maximum":100000},{"type":"string","enum":["viewport","max"]}]},"maxScrolls":{"type":"integer","minimum":1,"maximum":50},"selector":{"type":"string","minLength":1}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"screenshot"},"fullPage":{"type":"boolean"},"quality":{"type":"integer","minimum":1,"maximum":100},"viewport":{"type":"object","properties":{"width":{"type":"integer","minimum":200,"maximum":3840},"height":{"type":"integer","minimum":200,"maximum":2160}},"required":["width","height"],"additionalProperties":false}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scrape"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"executeJavascript"},"script":{"type":"string","minLength":1,"maxLength":20000}},"required":["type","script"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"pdf"},"format":{"type":"string","enum":["Letter","Legal","Tabloid","Ledger","A0","A1","A2","A3","A4","A5","A6"]},"landscape":{"type":"boolean"},"scale":{"type":"number","minimum":0.1,"maximum":2}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"perform"},"action":{"type":"string","minLength":1,"maxLength":500}},"required":["type","action"],"additionalProperties":false}]}},"location":{"description":"Where to read the page from. The default is the United States.","type":"object","properties":{"country":{"description":"Two-letter country code to read the page from, such as DE or JP.","type":"string"},"languages":{"description":"Languages to ask the site for, best first, such as [\"de\", \"en\"]. Sent as Accept-Language. A read with languages is never answered from or saved to a stored copy.","minItems":1,"maxItems":5,"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"}}},"additionalProperties":false},"removeBase64Images":{"description":"Images inside the page that carry their data in the address (data:image) are dropped by default. Send false to keep them in markdown and html.","type":"boolean"},"blockAds":{"description":"Ads and trackers are not loaded when a page runs in a browser. Send false to load them.","type":"boolean"},"fastMode":{"description":"Send true to read the page without opening a browser: the answer comes sooner, but a page that needs a browser, or that refuses a plain request, comes back as an error instead of being retried. Ignored when the call needs a browser (actions, screenshot, waitFor, mobile, profile, network, branding).","type":"boolean"},"proxy":{"description":"auto: basic first, enhanced once if the site refuses. basic: one plain attempt. enhanced: the stronger read from the start. stealth is the same as enhanced. Same price.","type":"string","enum":["auto","basic","enhanced","stealth"]},"storeInCache":{"default":true,"description":"Send false to neither read nor keep a stored copy of this page.","type":"boolean"},"lockdown":{"description":"Send true to answer only from a stored copy of the page and never read it live, whatever its age. A page with no stored copy is notFound. The same as minAge 0.","type":"boolean"},"checkPromptInjection":{"description":"Send true to scan the page text for instructions aimed at an AI model before anything is built from it. A page that has them is refused with 403 promptInjectionDetected and costs nothing. The scan adds 4 credits when it runs; a page it cannot scan fully comes back with a warning and no charge.","type":"boolean"},"redactPII":{"description":"Send true, or an object, to hide personal data in the markdown and in everything made from it (summary, answers, highlights, json). Links, html and rawHtml are not changed. A page the model cannot scan is refused rather than returned unredacted.","anyOf":[{"type":"boolean"},{"type":"object","properties":{"mode":{"default":"accurate","description":"accurate finds names and places with the model and the rest by pattern. aggressive adds guesses that catch more and may hide a little too much. fast uses patterns only, so it finds no ordinary names or places.","type":"string","enum":["accurate","aggressive","fast"]},"entities":{"default":["PERSON","EMAIL","PHONE","LOCATION","FINANCIAL","SECRET"],"description":"What to hide: PERSON, EMAIL, PHONE, LOCATION, FINANCIAL, SECRET. All by default.","minItems":1,"type":"array","items":{"type":"string","enum":["PERSON","EMAIL","PHONE","LOCATION","FINANCIAL","SECRET"]}},"replaceStyle":{"default":"tag","description":"tag writes <EMAIL>, mask writes * for each character, remove deletes it.","type":"string","enum":["tag","mask","remove"]}},"additionalProperties":false,"description":"Options for redactPII."}]},"profile":{"description":"Read the page with the cookies and local storage that earlier calls saved under this name, kept for your account for 30 days after the last use. A call with a profile always loads the page in a browser, costs 1 credit, the same as any page, and is never answered from a stored copy. Only one call at a time can save to a profile.","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128,"description":"A name you choose, such as shop-login. Calls with the same name share state."},"saveChanges":{"default":true,"description":"Keep the cookies and local storage this read leaves behind for the next call with this name. Send false to read with the profile without changing it.","type":"boolean"}},"required":["name"],"additionalProperties":false},"zeroDataRetention":{"default":false,"description":"Send true to keep nothing from this call: no stored copy is read or made, and nothing from it is logged. Costs 1 credit more per page. Not with a screenshot.","type":"boolean"},"linkStyle":{"default":"inline","description":"How links appear in the markdown. inline keeps [text](address). numbered writes Pricing⟨3⟩ and lists each address once at the end. none keeps only the link text, which makes link-heavy pages 10 to 70% shorter; ask for the links format to get the addresses.","type":"string","enum":["inline","numbered","none"]},"maxChars":{"description":"Cut the markdown at this many characters; isTruncated says when that happened and nextOffset where to read on. With query, how much of the page to keep, 8000 by default.","type":"integer","minimum":500,"maximum":1000000},"offset":{"description":"Start the markdown this many characters into the page, PDF or file. Send the nextOffset of the last answer, with the same maxChars, to read on. Not with query.","type":"integer","minimum":0,"maximum":9007199254740991},"query":{"description":"What you are looking for on the page, such as refund window. A page longer than maxChars (8000 by default) comes back as the passages that match, in page order, each with the text around it and its table header; a shorter page comes back whole. Costs nothing extra, and a PDF is charged for the share of its pages that comes back. Not with offset.","type":"string","minLength":1,"maxLength":10000},"urls":{"not":{}}},"required":["url"],"$defs":{"__schema0":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema0"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}}]},"__schema1":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema1"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema1"}}]},"__schema2":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema2"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema2"}}]}},"additionalProperties":false},"example":{"url":"https://bun.com/docs/runtime/bunfig"}},{"id":"extract","title":"Web Extract","summary":"Pull the fields you name from any public page as JSON, each checked against the page","bestWhen":"Best for a few facts from one page, like a price, a date or a list of names. Every field is checked against the page text and comes back null when the page does not state it. Use scrape for the whole page.","method":"POST","path":"/v1/extract","credits":5,"maxCredits":96,"pricing":"5 credits for most pages: the page's own price plus 4 credits. Each page after the first costs 1 credit more, and a long answer costs 1 credit more for every 64 values after the first 64, for each 40000 characters of page text read. A call that finds none of the fields is free","keyless":false,"cacheTtlSeconds":0,"input":{"type":"object","properties":{"urls":{"default":[],"description":"The pages to read, up to 25, such as [\"https://bun.com/blog/bun-v1.3\"]. An address ending in /* reads pages under it, found through the site's sitemap. With more than one, the fields are filled from all of them together. A page that cannot be read is skipped and named in warning, and costs nothing. A page is read up to 50000 characters. With several pages each one gets a smaller share, and all together are read up to 150000 characters. A page that is cut is counted in warning. The call fails only when no page can be read. Leave it out and send a prompt to search the web instead.","maxItems":25,"type":"array","items":{"type":"string","maxLength":2048}},"schema":{"description":"The fields to fill, as a JSON Schema (draft-07 or 2020-12) object with properties. Pydantic's model_json_schema() and zod's toJSONSchema() output work as they are. enum, const, anyOf, oneOf, nullable types, $ref with $defs, required, descriptions and any key names are read. Up to 100 top-level fields and 32 KB. A field the page does not state comes back null.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"prompt":{"description":"What to pull from the pages in plain words, such as the version and the release date, up to 10000 characters. With no urls, the web is searched for the first 400 characters of it.","type":"string","minLength":1,"maxLength":10000},"systemPrompt":{"description":"Standing instructions for how to fill the fields, such as units or how to write dates, up to 10000 characters. They add to the rules of the extract: a value is still copied from the page and is null when the page does not state it.","type":"string","minLength":1,"maxLength":10000},"enableWebSearch":{"default":false,"description":"Send true to also search the web for your prompt and read the best pages it finds, up to 3 more. Needs a prompt. Costs 2 credits for the search. With no urls, the search runs without this.","type":"boolean"},"allowExternalLinks":{"default":false,"description":"Send true to also read pages on other sites that the pages link to, up to 5, picking the links whose address mentions your prompt. Each page read costs 1 credit.","type":"boolean"},"agent":{"description":"Accepted so a client that sends { model: \"FIRE-1\" } works. An extract reads the pages it is given and checks every value; it does not browse or click, and the answer says so in warning. To navigate a site, use the agent endpoint.","type":"object","properties":{"model":{"type":"string","minLength":1,"maxLength":40}},"required":["model"],"additionalProperties":false},"webhook":{"description":"Where to be told when the extract ends: a plain address, or { url } which gets one JSON POST with the id, the status, the data and creditsUsed. headers are sent with the call, metadata comes back in it, and events picks completed, failed or both (both by default). The call is signed: read Stophy-Signature (t=<unix seconds>,v1=<hex>), the HMAC-SHA256 of \"<t>.<body>\" with your webhook secret from webhook.secret. A call that gets no 2xx is sent again, up to 3 times.","anyOf":[{"type":"string"},{"type":"object","properties":{"url":{"type":"string"},"headers":{"type":"object","propertyNames":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$"},"additionalProperties":{"type":"string","maxLength":1000}},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"events":{"minItems":1,"type":"array","items":{"type":"string","enum":["started","page","action","completed","failed","cancelled"]}}},"required":["url"],"additionalProperties":false}]},"ignoreSitemap":{"default":false,"description":"For an address ending in /*: skip the site's sitemaps and find pages by links.","type":"boolean"},"includeSubdomains":{"default":true,"description":"For an address ending in /*: also read pages on subdomains of the site. Send false to stay on the exact host.","type":"boolean"},"limit":{"description":"For an address ending in /*: read at most this many pages under it. At most 25 pages are read in all.","type":"integer","minimum":1,"maximum":9007199254740991},"timeout":{"default":30000,"description":"How long to keep reading the pages, in milliseconds, from 1 second to 5 minutes; 30 seconds by default. A page not read by then is skipped and named in warning, and costs nothing.","type":"integer","minimum":1000,"maximum":300000},"showSources":{"default":false,"description":"Send true to get sources: for each field, the pages that state its value.","type":"boolean"},"scrapeOptions":{"description":"How to read each page, the same options as scrape.","type":"object","properties":{"onlyMainContent":{"default":true,"description":"Keep only the page's main content, without menus, headers, footers and ads.","type":"boolean"},"onlyCleanContent":{"description":"Send true to have a model remove what onlyMainContent leaves behind in the markdown: cookie banners, ads, share widgets, breadcrumbs, sign-up prompts, comment prompts and related-article lists. It only removes whole paragraphs and lists; it never rewrites or adds text, and code blocks are always kept. Skipped with a warning when the page is too long to clean or the model does not answer. Not with zeroDataRetention. Summary, answers and highlights are made from the cleaned markdown.","type":"boolean"},"includeTags":{"description":"Keep only the parts of the page that match these CSS selectors, such as article or .price. When set, onlyMainContent is not applied.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"excludeTags":{"description":"Remove the parts of the page that match these CSS selectors, such as .comments.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"maxAge":{"description":"Accept a stored answer up to this many milliseconds old, at most 30 days. Without it, 2 days, or less for a site whose pages change often, and a copy up to twice that age (at most 7 days) comes back at once as stale while a fresh read runs. 0 always reads the page live. metadata.cacheState says which one you got.","type":"integer","minimum":0,"maximum":9007199254740991},"minAge":{"description":"Answer only from a stored copy that is at least this many milliseconds old, and never read the page live. 0 accepts any stored copy. A page with no such copy is notFound.","type":"integer","minimum":0,"maximum":9007199254740991},"headers":{"description":"Extra request headers to send to the site, such as { \"x-plan\": \"pro\" }. A read with headers is never answered from or saved to a stored copy.","type":"object","propertyNames":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$"},"additionalProperties":{"type":"string","maxLength":2000,"pattern":"^[\\t\\x20-\\x7e]*$"}},"waitFor":{"description":"Extra milliseconds to wait before reading, up to 60000, for pages that load their content late. To wait for an element, add a wait action with a selector. A read that waits costs 1 credit, the same as any page.","type":"integer","minimum":0,"maximum":60000},"mobile":{"description":"Read the page as a phone would: a phone-sized screen and the mobile version of the site. The page loads in a browser.","type":"boolean"},"skipTlsVerification":{"description":"Send true to read a page whose certificate is expired, self-signed or for another name. The read is not private against someone between us and the site.","type":"boolean"},"timeout":{"default":60000,"description":"How long to keep trying, in milliseconds, from 1 second to 5 minutes; 60 seconds by default. A page that needs a browser needs at least 5 seconds, and pages behind a bot check can need 10 to 30 seconds the first time. A read that runs out of time is an error and costs nothing.","type":"integer","minimum":1000,"maximum":300000},"parsers":{"description":"Only the pdf parser exists. Send \"pdf\" or { \"type\": \"pdf\", mode, maxPages, pages, blocks, pageMarkers } with the same meaning as in parse. Without mode a PDF is read as auto: from its text layer, and from the picture of any page that has no text. fast reads the text layer only, and ocr reads the picture of every page, up to 20 pages. Each page of text that comes back costs 1 credit. Pictures are read only with an API key.","minItems":1,"type":"array","items":{"anyOf":[{"type":"string","const":"pdf"},{"type":"object","properties":{"type":{"type":"string","const":"pdf"},"mode":{"description":"fast reads the text layer only. auto (the default) reads the text layer and reads the picture of any page that has none. ocr reads the picture of every page.","type":"string","enum":["fast","auto","ocr"]},"maxPages":{"description":"Read at most this many pages, up to 500, which is also the default.","type":"integer","minimum":1,"maximum":500},"pages":{"description":"Send true to also get each page's markdown in pages, as { pageNumber, markdown }. No extra charge.","type":"boolean"},"blocks":{"description":"Send true to also get the page's layout in blocks: each title, section header or run of text, with its page, reading order, position on the page (bbox as left, top, right, bottom from 0 to 1) and where its text sits in that page's markdown (span, as in pages). Tables, figures and formulas are not told apart. A page read from its picture is one block. No extra charge.","type":"boolean"},"pageMarkers":{"description":"Send true to mark page breaks in the markdown: pages are joined with \"---\" and a <!-- page N --> line, where N is the page that follows. No extra charge.","type":"boolean"}},"required":["type"],"additionalProperties":false}]}},"actions":{"description":"Up to 50 steps to run on the page, in order, before reading it: { \"type\": \"wait\", \"milliseconds\": 500 } (up to 60 seconds), { \"type\": \"wait\", \"selector\": \".results\" }, { \"type\": \"click\", \"selector\": \"button.more\" }, { \"type\": \"write\", \"text\": \"tides\" }, { \"type\": \"press\", \"key\": \"Enter\" }, { \"type\": \"scroll\", \"direction\": \"down\" } (also up, left or right; amount is pixels, \"viewport\" or \"max\"; maxScrolls 1 to 50; selector scrolls an inner container; \"max\" keeps scrolling until the page stops growing, for feeds that load as you go), { \"type\": \"screenshot\", \"fullPage\": true } (links come back in actions.screenshots), { \"type\": \"scrape\" } (the page at that point, in actions.scrapes), { \"type\": \"executeJavascript\", \"script\": \"document.title\" } (results in actions.javascriptReturns), { \"type\": \"pdf\", \"format\": \"A4\" } (links in actions.pdfs) or { \"type\": \"perform\", \"action\": \"Click the Load more button\" } (a step in plain words, up to 5 browser steps on this page, never leaving the site; at most 5 per call). A read with actions costs 1 credit, the same as any page; the actions themselves add nothing. If an action fails, you still get the page as it stood, with a warning that names the action and says why.","minItems":1,"maxItems":50,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"wait"},"milliseconds":{"type":"integer","minimum":1,"maximum":60000}},"required":["type","milliseconds"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"wait"},"selector":{"type":"string","minLength":1}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"click"},"selector":{"type":"string","minLength":1},"all":{"type":"boolean","const":false}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"write"},"text":{"type":"string","minLength":1}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"press"},"key":{"type":"string","minLength":1,"maxLength":40}},"required":["type","key"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scroll"},"direction":{"default":"down","type":"string","enum":["up","down","left","right"]},"amount":{"anyOf":[{"type":"integer","minimum":1,"maximum":100000},{"type":"string","enum":["viewport","max"]}]},"maxScrolls":{"type":"integer","minimum":1,"maximum":50},"selector":{"type":"string","minLength":1}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"screenshot"},"fullPage":{"type":"boolean"},"quality":{"type":"integer","minimum":1,"maximum":100},"viewport":{"type":"object","properties":{"width":{"type":"integer","minimum":200,"maximum":3840},"height":{"type":"integer","minimum":200,"maximum":2160}},"required":["width","height"],"additionalProperties":false}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scrape"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"executeJavascript"},"script":{"type":"string","minLength":1,"maxLength":20000}},"required":["type","script"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"pdf"},"format":{"type":"string","enum":["Letter","Legal","Tabloid","Ledger","A0","A1","A2","A3","A4","A5","A6"]},"landscape":{"type":"boolean"},"scale":{"type":"number","minimum":0.1,"maximum":2}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"perform"},"action":{"type":"string","minLength":1,"maxLength":500}},"required":["type","action"],"additionalProperties":false}]}},"location":{"description":"Where to read the page from. The default is the United States.","type":"object","properties":{"country":{"description":"Two-letter country code to read the page from, such as DE or JP.","type":"string"},"languages":{"description":"Languages to ask the site for, best first, such as [\"de\", \"en\"]. Sent as Accept-Language. A read with languages is never answered from or saved to a stored copy.","minItems":1,"maxItems":5,"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"}}},"additionalProperties":false},"removeBase64Images":{"description":"Images inside the page that carry their data in the address (data:image) are dropped by default. Send false to keep them in markdown and html.","type":"boolean"},"blockAds":{"description":"Ads and trackers are not loaded when a page runs in a browser. Send false to load them.","type":"boolean"},"fastMode":{"description":"Send true to read the page without opening a browser: the answer comes sooner, but a page that needs a browser, or that refuses a plain request, comes back as an error instead of being retried. Ignored when the call needs a browser (actions, screenshot, waitFor, mobile, profile, network, branding).","type":"boolean"},"proxy":{"description":"auto: basic first, enhanced once if the site refuses. basic: one plain attempt. enhanced: the stronger read from the start. stealth is the same as enhanced. Same price.","type":"string","enum":["auto","basic","enhanced","stealth"]},"storeInCache":{"default":true,"description":"Send false to neither read nor keep a stored copy of this page.","type":"boolean"},"lockdown":{"description":"Send true to answer only from a stored copy of the page and never read it live, whatever its age. A page with no stored copy is notFound. The same as minAge 0.","type":"boolean"},"checkPromptInjection":{"description":"Send true to scan the page text for instructions aimed at an AI model before anything is built from it. A page that has them is refused with 403 promptInjectionDetected and costs nothing. The scan adds 4 credits when it runs; a page it cannot scan fully comes back with a warning and no charge.","type":"boolean"},"redactPII":{"description":"Send true, or an object, to hide personal data in the markdown and in everything made from it (summary, answers, highlights, json). Links, html and rawHtml are not changed. A page the model cannot scan is refused rather than returned unredacted.","anyOf":[{"type":"boolean"},{"type":"object","properties":{"mode":{"default":"accurate","description":"accurate finds names and places with the model and the rest by pattern. aggressive adds guesses that catch more and may hide a little too much. fast uses patterns only, so it finds no ordinary names or places.","type":"string","enum":["accurate","aggressive","fast"]},"entities":{"default":["PERSON","EMAIL","PHONE","LOCATION","FINANCIAL","SECRET"],"description":"What to hide: PERSON, EMAIL, PHONE, LOCATION, FINANCIAL, SECRET. All by default.","minItems":1,"type":"array","items":{"type":"string","enum":["PERSON","EMAIL","PHONE","LOCATION","FINANCIAL","SECRET"]}},"replaceStyle":{"default":"tag","description":"tag writes <EMAIL>, mask writes * for each character, remove deletes it.","type":"string","enum":["tag","mask","remove"]}},"additionalProperties":false,"description":"Options for redactPII."}]},"profile":{"description":"Read the page with the cookies and local storage that earlier calls saved under this name, kept for your account for 30 days after the last use. A call with a profile always loads the page in a browser, costs 1 credit, the same as any page, and is never answered from a stored copy. Only one call at a time can save to a profile.","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128,"description":"A name you choose, such as shop-login. Calls with the same name share state."},"saveChanges":{"default":true,"description":"Keep the cookies and local storage this read leaves behind for the next call with this name. Send false to read with the profile without changing it.","type":"boolean"}},"required":["name"],"additionalProperties":false},"zeroDataRetention":{"default":false,"description":"Send true to keep nothing from this call: no stored copy is read or made, and nothing from it is logged. Costs 1 credit more per page. Not with a screenshot.","type":"boolean"}},"additionalProperties":false},"zeroDataRetention":{"default":false,"description":"Send true to keep nothing from this call: pages are read live, the result is held for one hour at most, and nothing is logged. Costs 1 credit more per page.","type":"boolean"},"ignoreInvalidURLs":{"default":true,"description":"Skip addresses that are not public website URLs. Send false to refuse the call instead.","type":"boolean"}},"$defs":{"__schema0":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema0"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}}]}},"additionalProperties":false},"example":{"urls":["https://bun.com/docs/runtime/bunfig"],"schema":{"type":"object","properties":{"file":{"type":"string"}}},"prompt":"What is the name of the configuration file this page describes?"}},{"id":"browser.task","title":"Browser Task","summary":"Click through a public website in a real browser to search, filter or fill a form","bestWhen":"Best for a few steps a person would click through on a public site, like a search with filters or a form to fill without sending it. It answers at once with an id; ask browser.task.status for the result. A task takes up to 50 steps and 10 minutes, and stops before anything that pays, books, sends, submits or deletes. Stophy never logs in to a site.","method":"POST","path":"/v1/browser/task","credits":0,"maxCredits":70,"pricing":"7 credits for each browser minute the task runs, one minute at least, up to maxCost. A task that ends before its first step costs nothing. Starting a task sets aside the most it can cost, and what it does not use comes back when it ends","keyless":false,"cacheTtlSeconds":0,"input":{"type":"object","properties":{"url":{"description":"The public page to start on, such as https://www.python.org.","type":"string"},"goal":{"type":"string","minLength":1,"maxLength":1000,"description":"What to get done on the page, in one or two sentences."},"values":{"description":"Values the steps will need, such as: from London, to Istanbul, date 2026-12-01. They are typed only on the start page's site.","type":"string","maxLength":1000},"schema":{"description":"Fields to fill when the task is done, as a JSON Schema object. Each one is checked against the pages the task saw and comes back null when no page states it.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"maxSteps":{"default":50,"description":"The most steps the task may take, 1 to 50.","type":"integer","minimum":1,"maximum":50},"maxCost":{"description":"The most the task may spend, in US dollars at the standard price of $0.002 a credit. Each browser minute is 7 credits, so $0.014, and the task stops when this is spent. Leave out to allow the full 10 minutes.","type":"number","exclusiveMinimum":0}},"required":["url","goal"],"$defs":{"__schema0":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema0"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}}]}},"additionalProperties":false},"example":null},{"id":"browser.task.status","title":"Browser Task Status","summary":"Check a browser task and read its result","bestWhen":"result is null while the task runs. When it ends, result says whether the goal was met, the answer, why it stopped if not, and the steps taken. A task is kept for 24 hours.","method":"POST","path":"/v1/browser/task/status","credits":0,"maxCredits":0,"pricing":null,"keyless":false,"cacheTtlSeconds":0,"input":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"The id browser.task returned."}},"required":["id"],"additionalProperties":false},"example":null},{"id":"parse","title":"Web Parse","summary":"Turn a PDF, Word, Excel, PowerPoint or HTML file, or a picture of text, into markdown","bestWhen":"Best for a file you already hold. To read a page or a PDF by its address, use scrape.","method":"POST","path":"/v1/parse","credits":1,"maxCredits":101,"pricing":"1 credit for each PDF page whose text comes back, from its text layer or its picture, up to maxPages; 1 credit for any other file; zero data retention adds 1. creditsUsed shows what the call cost","keyless":true,"cacheTtlSeconds":0,"input":{"type":"object","properties":{"formats":{"description":"What to send back besides markdown: summary, html and rawHtml (HTML files only), links, images, or { type: json, schema or prompt }. markdown is always sent.","minItems":1,"maxItems":8,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"json"},"prompt":{"type":"string","minLength":1,"maxLength":2000},"schema":{"description":"The fields to fill, as a JSON Schema (draft-07 or 2020-12) object with properties. Pydantic's model_json_schema() and zod's toJSONSchema() output work as they are. enum, const, anyOf, oneOf, nullable types, $ref with $defs, required, descriptions and any key names are read. Up to 100 top-level fields and 32 KB. A field the page does not state comes back null.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}}},"required":["type"],"additionalProperties":false},{"anyOf":[{"type":"string","enum":["markdown","summary","html","rawHtml","links","images"]},{"type":"object","properties":{"type":{"type":"string","enum":["markdown","summary","html","rawHtml","links","images"]}},"required":["type"],"additionalProperties":false}]}]}},"parsers":{"description":"How to read PDF pages. Other files ignore it.","maxItems":1,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"pdf"},"mode":{"description":"fast reads the text layer only. auto (the default) reads the text layer and reads the picture of any page that has none. ocr reads the picture of every page.","type":"string","enum":["fast","auto","ocr"]},"maxPages":{"description":"Read at most this many pages, up to 100.","type":"integer","minimum":1,"maximum":100},"pages":{"description":"Send true to also get each page's markdown in pages, as { pageNumber, markdown }. No extra charge.","type":"boolean"},"blocks":{"description":"Send true to also get the page's layout in blocks: each title, section header or run of text, with its page, reading order, position on the page (bbox as left, top, right, bottom from 0 to 1) and where its text sits in that page's markdown (span, as in pages). Tables, figures and formulas are not told apart. A page read from its picture is one block. No extra charge.","type":"boolean"},"pageMarkers":{"description":"Send true to mark page breaks in the markdown: pages are joined with \"---\" and a <!-- page N --> line, where N is the page that follows. No extra charge.","type":"boolean"}},"required":["type"],"additionalProperties":false}},"onlyMainContent":{"description":"For an HTML file: send false to keep navigation and footers. The default is true.","type":"boolean"},"includeTags":{"description":"For an HTML file: keep only what these CSS selectors match.","maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"excludeTags":{"description":"For an HTML file: drop what these CSS selectors match.","maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"removeBase64Images":{"description":"For an HTML file: send false to keep images that carry their data in the address.","type":"boolean"},"zeroDataRetention":{"default":false,"description":"Send true to keep nothing from this call: no stored result is read or made, and nothing is logged. Costs 1 credit more.","type":"boolean"},"origin":{"description":"Which client sent the call. Not used.","type":"string","maxLength":200},"integration":{"description":"Which integration sent the call. Not used.","type":"string","maxLength":200},"fastMode":{"description":"Page-read speed. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."},"mobile":{"description":"Mobile page view. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."},"blockAds":{"description":"Ad blocking. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."},"skipTlsVerification":{"description":"TLS checks of a page. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."},"timeout":{"description":"Page load time. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."},"headers":{"description":"Page request headers. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."},"proxy":{"description":"Page proxy. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."},"location":{"description":"Page country and languages. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."},"profile":{"description":"Saved browser profile. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."},"uploadRef":{"description":"Instead of file: the uploadId that POST /v1/parse/upload-url returned, after the file was sent to its uploadUrl. The stored file is deleted when the parse ends.","type":"string","pattern":"^upl_[A-Za-z0-9_-]{16,64}$"},"file":{"description":"The file's bytes as base64, up to 36 MB: a PDF, a Word .docx, an Excel .xlsx, a PowerPoint .pptx, an HTML file or a PNG, JPEG or WebP picture of text.","type":"string","minLength":1},"filename":{"description":"The file's name, such as report.docx. The type is read from the file itself.","type":"string","minLength":1,"maxLength":255},"maxPages":{"default":100,"description":"Read at most this many PDF pages, sheets or slides; isTruncated says when the file had more. Pages of a PDF with no text layer are read from their picture, up to 20 of them, with no extra charge.","type":"integer","minimum":1,"maximum":100},"options":{"type":"object","properties":{"formats":{"description":"What to send back besides markdown: summary, html and rawHtml (HTML files only), links, images, or { type: json, schema or prompt }. markdown is always sent.","minItems":1,"maxItems":8,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"json"},"prompt":{"type":"string","minLength":1,"maxLength":2000},"schema":{"description":"The fields to fill, as a JSON Schema (draft-07 or 2020-12) object with properties. Pydantic's model_json_schema() and zod's toJSONSchema() output work as they are. enum, const, anyOf, oneOf, nullable types, $ref with $defs, required, descriptions and any key names are read. Up to 100 top-level fields and 32 KB. A field the page does not state comes back null.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}}},"required":["type"],"additionalProperties":false},{"anyOf":[{"type":"string","enum":["markdown","summary","html","rawHtml","links","images"]},{"type":"object","properties":{"type":{"type":"string","enum":["markdown","summary","html","rawHtml","links","images"]}},"required":["type"],"additionalProperties":false}]}]}},"parsers":{"description":"How to read PDF pages. Other files ignore it.","maxItems":1,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","const":"pdf"},"mode":{"description":"fast reads the text layer only. auto (the default) reads the text layer and reads the picture of any page that has none. ocr reads the picture of every page.","type":"string","enum":["fast","auto","ocr"]},"maxPages":{"description":"Read at most this many pages, up to 100.","type":"integer","minimum":1,"maximum":100},"pages":{"description":"Send true to also get each page's markdown in pages, as { pageNumber, markdown }. No extra charge.","type":"boolean"},"blocks":{"description":"Send true to also get the page's layout in blocks: each title, section header or run of text, with its page, reading order, position on the page (bbox as left, top, right, bottom from 0 to 1) and where its text sits in that page's markdown (span, as in pages). Tables, figures and formulas are not told apart. A page read from its picture is one block. No extra charge.","type":"boolean"},"pageMarkers":{"description":"Send true to mark page breaks in the markdown: pages are joined with \"---\" and a <!-- page N --> line, where N is the page that follows. No extra charge.","type":"boolean"}},"required":["type"],"additionalProperties":false}},"onlyMainContent":{"description":"For an HTML file: send false to keep navigation and footers. The default is true.","type":"boolean"},"includeTags":{"description":"For an HTML file: keep only what these CSS selectors match.","maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"excludeTags":{"description":"For an HTML file: drop what these CSS selectors match.","maxItems":50,"type":"array","items":{"type":"string","minLength":1}},"removeBase64Images":{"description":"For an HTML file: send false to keep images that carry their data in the address.","type":"boolean"},"zeroDataRetention":{"type":"boolean"},"origin":{"description":"Which client sent the call. Not used.","type":"string","maxLength":200},"integration":{"description":"Which integration sent the call. Not used.","type":"string","maxLength":200},"fastMode":{"description":"Page-read speed. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."},"mobile":{"description":"Mobile page view. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."},"blockAds":{"description":"Ad blocking. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."},"skipTlsVerification":{"description":"TLS checks of a page. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."},"timeout":{"description":"Page load time. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."},"headers":{"description":"Page request headers. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."},"proxy":{"description":"Page proxy. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."},"location":{"description":"Page country and languages. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."},"profile":{"description":"Saved browser profile. Accepted so a client that always sends it works; a file has no page to apply it to, so it is not used."}},"additionalProperties":false,"description":"How to read the file and what to send back, with the same names scrape uses for a page."}},"$defs":{"__schema0":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema0"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}}]}},"additionalProperties":false},"example":{"file":"PGh0bWw+PGhlYWQ+PHRpdGxlPkhvdyB0aWRlcyB3b3JrPC90aXRsZT48L2hlYWQ+PGJvZHk+PG1haW4+PGgxPkhvdyB0aWRlcyB3b3JrPC9oMT48cD5UaGUgTW9vbiBwdWxscyBvbiB0aGUgb2NlYW5zIGFuZCBtYWtlcyB0d28gYnVsZ2VzIG9mIHdhdGVyIHRoYXQgbW92ZSBhcm91bmQgdGhlIEVhcnRoIGFzIGl0IHR1cm5zLCBzbyBtb3N0IGNvYXN0cyBzZWUgdHdvIGhpZ2ggdGlkZXMgYW5kIHR3byBsb3cgdGlkZXMgZXZlcnkgZGF5LjwvcD48L21haW4+PC9ib2R5PjwvaHRtbD4=","filename":"tides.html"}},{"id":"map","title":"Web Map","summary":"Scrape the list of pages on a website","bestWhen":"Best for finding the right page on a site before reading it with scrape. Add search to rank pages about one topic first.","method":"POST","path":"/v1/map","credits":1,"maxCredits":1,"pricing":null,"keyless":true,"cacheTtlSeconds":21600,"input":{"type":"object","properties":{"url":{"description":"Any page of the site to map, such as https://bun.com.","type":"string"},"search":{"description":"Keep only addresses that mention these words, best matches first, such as pricing.","type":"string","minLength":1},"sitemap":{"default":"include","description":"include uses the site's sitemaps and its pages. only lists just what the sitemaps name. skip ignores the sitemaps.","type":"string","enum":["skip","include","only"]},"includeSubdomains":{"default":true,"description":"Also list pages on subdomains, such as docs.bun.com for bun.com.","type":"boolean"},"ignoreQueryParameters":{"default":true,"description":"List each page once, without its ?query part.","type":"boolean"},"ignoreCache":{"default":false,"description":"Send true to build the list again instead of reusing one made in the last 6 hours.","type":"boolean"},"limit":{"default":5000,"description":"The most addresses to return, up to 100000.","type":"integer","minimum":1,"maximum":100000},"timeout":{"description":"Stop looking after this many milliseconds and return what was found.","type":"integer","minimum":1000,"maximum":9007199254740991},"location":{"description":"Where to read the page from. The default is the United States.","type":"object","properties":{"country":{"description":"Two-letter country code to read the page from, such as DE or JP.","type":"string"},"languages":{"description":"Languages to ask the site for, best first, such as [\"de\", \"en\"]. Sent as Accept-Language. A read with languages is never answered from or saved to a stored copy.","minItems":1,"maxItems":5,"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"}}},"additionalProperties":false}},"required":["url"],"additionalProperties":false},"example":{"url":"https://bun.com","search":"sqlite"}},{"id":"crawl","title":"Web Crawl Start","summary":"Crawl a website in the background","bestWhen":"Best for reading a whole section of a site without holding a call open. It answers at once with an id; ask crawl.status for the pages, or send webhook to be told as each one finishes.","method":"POST","path":"/v1/crawl","credits":0,"maxCredits":300000,"pricing":"1 credit a page, however it is reached. checkPromptInjection adds 4 credits when the scan runs, json with a schema or a prompt, summary, highlights, question, product, menu and changeTracking in json mode add 4 credits each when they return something. CSS rules and attributes add nothing. A PDF adds 1 credit for each page of text that comes back, so a PDF read with maxChars, offset or query is charged for the share of its pages that it returns, at least 1 page. Browser actions add nothing. An answer from a stored copy within maxAge costs 1 credit like any page. A page that comes back with a 404 or 410 status, or cannot be read, costs nothing. Each page is charged when it finishes. Starting the job is free","keyless":false,"cacheTtlSeconds":0,"input":{"type":"object","properties":{"url":{"description":"The page to start from, such as https://bun.com/docs.","type":"string"},"prompt":{"description":"What you are looking for, such as sqlite performance. Pages about it are read first, and the crawl stops once new pages stop mentioning it.","type":"string","minLength":1,"maxLength":1000},"includePaths":{"default":[],"description":"Read only pages whose path matches one of these regular expressions, such as blog/.*.","maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"excludePaths":{"default":[],"description":"Skip pages whose path matches one of these regular expressions, such as tag/.*.","maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"maxDiscoveryDepth":{"description":"How many links away from the start page to go. Without it there is no depth limit, and limit bounds the crawl.","type":"integer","minimum":0,"maximum":9007199254740991},"sitemap":{"default":"include","description":"include also uses the site's sitemaps. only reads just the pages the sitemaps name. skip ignores them.","type":"string","enum":["skip","include","only"]},"ignoreQueryParameters":{"default":false,"description":"Treat addresses that differ only in their ?query part as one page.","type":"boolean"},"regexOnFullURL":{"default":false,"description":"Match includePaths and excludePaths against the whole address, not only the path.","type":"boolean"},"limit":{"default":10000,"description":"Stop after reading this many pages in total.","type":"integer","minimum":1,"maximum":10000},"crawlEntireDomain":{"default":false,"description":"Read the whole site, not only pages under the start page's path.","type":"boolean"},"deduplicateSimilarURLs":{"default":true,"description":"Read one page when addresses differ only by www, a trailing slash, a #fragment, tracking parameters such as utm_source, or the order of the ?query. Send false to read each address.","type":"boolean"},"allowExternalLinks":{"default":false,"description":"Also follow links to other sites. They count toward limit and maxDiscoveryDepth. Only the start site's robots.txt is read.","type":"boolean"},"allowSubdomains":{"default":false,"description":"Also read pages on subdomains, such as docs.bun.com for bun.com.","type":"boolean"},"delay":{"description":"Seconds to wait between pages. With delay the crawl reads one page at a time. At most 60.","type":"number","minimum":0,"maximum":60},"maxConcurrency":{"description":"Most pages read at once. We read at most 4 at once, so a larger number gives the same speed.","type":"integer","minimum":1,"maximum":100},"scrapeOptions":{"description":"How to read each page, the same options and formats as scrape. Without formats, each page comes back as markdown.","type":"object","properties":{"formats":{"description":"What to return: markdown (clean page text), summary (a short summary of the page), html (the cleaned page), rawHtml (the page as sent), audio and video (for a YouTube link: the audio track as an M4A file, or the video as an MP4 file, as a link that works for 1 hour), rawBase64 (the bytes the site sent, Base64 encoded, from a live read; metadata.contentType says what they are), links (every link on the page), images (every image address), screenshot (a link to a JPEG of the visible page, kept for 7 days), changeTracking (what changed in the markdown since your key last read this page with the same options, kept 30 days; add modes [\"git-diff\",\"json\"] with a schema or prompt to compare fields too), question (send { \"type\": \"question\", \"question\": \"...\" } to get answer, null when the page does not state one), product (title, brand, category, url, description and variants with price, sale, availability and images, or null) and menu (merchant, currency and sections of items with prices, or null) network (the JSON the page loaded while it rendered, up to 30 responses) and branding (the page's colors, fonts, typography, spacing, button and input styles, logo and brand images, read from how the page looks, with a field left out when the page does not show it). Send { \"type\": \"screenshot\", \"fullPage\": true } for the whole page. Send { \"type\": \"highlights\", \"query\": \"refund policy\" } for the passages that best match a query. Send { \"type\": \"json\", \"schema\": { \"type\": \"object\", \"properties\": { \"price\": { \"type\": \"number\" } } } } or { \"type\": \"json\", \"prompt\": \"the price and the stock\" } for fields filled from the page, each checked against it. Send { \"type\": \"json\", \"parser\": \"amazon-product\" } to get a site's own data as json instead of reading the page; GET /v1/parsers lists the parsers. Send { \"type\": \"json\", \"rules\": { \"title\": \"h1\", \"links\": { \"selector\": \"a\", \"type\": \"list\", \"output\": \"@href\" } } } to read the page with CSS rules and no model, at the page's own price. Send { \"type\": \"attributes\", \"selectors\": [{ \"selector\": \"a\", \"attribute\": \"href\" }] } for attribute values, returned in attributes. Without a parser or rules, json needs a schema or a prompt and is filled from the page. json with a schema or a prompt, summary, highlights, question, product, menu and changeTracking in json mode cost 4 credits more each when they return something. json with rules or a parser, and attributes, cost nothing more. A screenshot, network or branding read costs 1 credit, the same as any page. A PDF comes back as markdown only, and costs 1 credit more for each page of text that comes back. A CSV or an Excel .xlsx file comes back as markdown tables.","default":["markdown"],"minItems":1,"maxItems":20,"type":"array","items":{"anyOf":[{"type":"string","enum":["markdown","summary","html","rawHtml","rawBase64","links","images","network","branding","audio","video","screenshot","changeTracking","product","menu"]},{"type":"object","properties":{"type":{"type":"string","enum":["markdown","summary","html","rawHtml","rawBase64","links","images","network","branding","audio","video"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"changeTracking"},"modes":{"description":"git-diff returns a unified diff of the markdown. json compares the fields in schema or prompt between this read and the last one. Without modes you get git-diff.","maxItems":2,"type":"array","items":{"type":"string","enum":["git-diff","json"]}},"schema":{"description":"The fields to fill, as a JSON Schema (draft-07 or 2020-12) object with properties. Pydantic's model_json_schema() and zod's toJSONSchema() output work as they are. enum, const, anyOf, oneOf, nullable types, $ref with $defs, required, descriptions and any key names are read. Up to 100 top-level fields and 32 KB. A field the page does not state comes back null.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"prompt":{"description":"With json mode: what to compare, in plain words, such as the price and stock.","type":"string","minLength":1,"maxLength":10000},"tag":{"type":"null"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"question"},"question":{"type":"string","minLength":1,"maxLength":10000,"description":"A question to answer from the page, such as what the refund window is."}},"required":["type","question"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"product"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"menu"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"screenshot"},"fullPage":{"default":false,"description":"Capture the whole page from top to bottom instead of the visible part.","type":"boolean"},"quality":{"description":"JPEG quality from 1 to 100. The default is 70.","type":"integer","minimum":1,"maximum":100},"viewport":{"description":"The window size in pixels, such as { width: 390, height: 844 }.","type":"object","properties":{"width":{"type":"integer","minimum":200,"maximum":3840},"height":{"type":"integer","minimum":200,"maximum":2160}},"required":["width","height"],"additionalProperties":false}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"highlights"},"query":{"type":"string","minLength":1,"maxLength":10000,"description":"What you are looking for on the page, such as refund policy."},"count":{"default":5,"description":"How many passages to return, best match first.","type":"integer","minimum":1,"maximum":20}},"required":["type","query"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"json"},"parser":{"description":"Read the page with a named parser, which gives the site's own data as json. The url must be the kind of page the parser reads. Parsers are the only way to read some sites. GET /v1/parsers lists them.","type":"string"},"options":{"description":"Only with parser: extra inputs for it, such as { \"page\": 2 } for the next page of results or { \"minRating\": 4.5 } for a filter. GET /v1/parsers lists what each parser accepts.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema1"}},"schema":{"description":"The fields to fill, as a JSON Schema (draft-07 or 2020-12) object with properties. Pydantic's model_json_schema() and zod's toJSONSchema() output work as they are. enum, const, anyOf, oneOf, nullable types, $ref with $defs, required, descriptions and any key names are read. Up to 100 top-level fields and 32 KB. A field the page does not state comes back null.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"prompt":{"description":"What to pull from the page in plain words, such as the version and the release date.","type":"string","minLength":1,"maxLength":10000},"rules":{"description":"Read the page with CSS rules instead of a model, no extra fee. Each field is a selector such as \"h1\" (the first match's text), \"a@href\" (an attribute) or { \"selector\": \"li\", \"type\": \"list\", \"output\": \"text\" | \"html\" | \"@attribute\" | { nested fields } }. A missing item is null and an unmatched list is []. Relative links become absolute. Up to 100 fields, 5 levels deep. Not with schema, prompt or parser.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema2"}},"checkPromptInjection":{"description":"Deprecated: send checkPromptInjection at the top level of the call.","type":"boolean"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"attributes"},"selectors":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"selector":{"type":"string","minLength":1},"attribute":{"type":"string","minLength":1,"maxLength":100}},"required":["selector","attribute"],"additionalProperties":false},"description":"The elements and attributes to read, such as { selector: 'a.buy', attribute: 'href' }."}},"required":["type","selectors"],"additionalProperties":false}]}},"onlyMainContent":{"default":true,"description":"Keep only the page's main content, without menus, headers, footers and ads.","type":"boolean"},"onlyCleanContent":{"description":"Send true to have a model remove what onlyMainContent leaves behind in the markdown: cookie banners, ads, share widgets, breadcrumbs, sign-up prompts, comment prompts and related-article lists. It only removes whole paragraphs and lists; it never rewrites or adds text, and code blocks are always kept. Skipped with a warning when the page is too long to clean or the model does not answer. Not with zeroDataRetention. Summary, answers and highlights are made from the cleaned markdown.","type":"boolean"},"includeTags":{"description":"Keep only the parts of the page that match these CSS selectors, such as article or .price. When set, onlyMainContent is not applied.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"excludeTags":{"description":"Remove the parts of the page that match these CSS selectors, such as .comments.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"maxAge":{"description":"Accept a stored answer up to this many milliseconds old, at most 30 days. Without it, 2 days, or less for a site whose pages change often, and a copy up to twice that age (at most 7 days) comes back at once as stale while a fresh read runs. 0 always reads the page live. metadata.cacheState says which one you got.","type":"integer","minimum":0,"maximum":9007199254740991},"minAge":{"description":"Answer only from a stored copy that is at least this many milliseconds old, and never read the page live. 0 accepts any stored copy. A page with no such copy is notFound.","type":"integer","minimum":0,"maximum":9007199254740991},"headers":{"description":"Extra request headers to send to the site, such as { \"x-plan\": \"pro\" }. A read with headers is never answered from or saved to a stored copy.","type":"object","propertyNames":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$"},"additionalProperties":{"type":"string","maxLength":2000,"pattern":"^[\\t\\x20-\\x7e]*$"}},"waitFor":{"description":"Extra milliseconds to wait before reading, up to 60000, for pages that load their content late. To wait for an element, add a wait action with a selector. A read that waits costs 1 credit, the same as any page.","type":"integer","minimum":0,"maximum":60000},"mobile":{"description":"Read the page as a phone would: a phone-sized screen and the mobile version of the site. The page loads in a browser.","type":"boolean"},"skipTlsVerification":{"description":"Send true to read a page whose certificate is expired, self-signed or for another name. The read is not private against someone between us and the site.","type":"boolean"},"timeout":{"default":60000,"description":"How long to keep trying, in milliseconds, from 1 second to 5 minutes; 60 seconds by default. A page that needs a browser needs at least 5 seconds, and pages behind a bot check can need 10 to 30 seconds the first time. A read that runs out of time is an error and costs nothing.","type":"integer","minimum":1000,"maximum":300000},"parsers":{"description":"Only the pdf parser exists. Send \"pdf\" or { \"type\": \"pdf\", mode, maxPages, pages, blocks, pageMarkers } with the same meaning as in parse. Without mode a PDF is read as auto: from its text layer, and from the picture of any page that has no text. fast reads the text layer only, and ocr reads the picture of every page, up to 20 pages. Each page of text that comes back costs 1 credit. Pictures are read only with an API key.","minItems":1,"type":"array","items":{"anyOf":[{"type":"string","const":"pdf"},{"type":"object","properties":{"type":{"type":"string","const":"pdf"},"mode":{"description":"fast reads the text layer only. auto (the default) reads the text layer and reads the picture of any page that has none. ocr reads the picture of every page.","type":"string","enum":["fast","auto","ocr"]},"maxPages":{"description":"Read at most this many pages, up to 500, which is also the default.","type":"integer","minimum":1,"maximum":500},"pages":{"description":"Send true to also get each page's markdown in pages, as { pageNumber, markdown }. No extra charge.","type":"boolean"},"blocks":{"description":"Send true to also get the page's layout in blocks: each title, section header or run of text, with its page, reading order, position on the page (bbox as left, top, right, bottom from 0 to 1) and where its text sits in that page's markdown (span, as in pages). Tables, figures and formulas are not told apart. A page read from its picture is one block. No extra charge.","type":"boolean"},"pageMarkers":{"description":"Send true to mark page breaks in the markdown: pages are joined with \"---\" and a <!-- page N --> line, where N is the page that follows. No extra charge.","type":"boolean"}},"required":["type"],"additionalProperties":false}]}},"actions":{"description":"Up to 50 steps to run on the page, in order, before reading it: { \"type\": \"wait\", \"milliseconds\": 500 } (up to 60 seconds), { \"type\": \"wait\", \"selector\": \".results\" }, { \"type\": \"click\", \"selector\": \"button.more\" }, { \"type\": \"write\", \"text\": \"tides\" }, { \"type\": \"press\", \"key\": \"Enter\" }, { \"type\": \"scroll\", \"direction\": \"down\" } (also up, left or right; amount is pixels, \"viewport\" or \"max\"; maxScrolls 1 to 50; selector scrolls an inner container; \"max\" keeps scrolling until the page stops growing, for feeds that load as you go), { \"type\": \"screenshot\", \"fullPage\": true } (links come back in actions.screenshots), { \"type\": \"scrape\" } (the page at that point, in actions.scrapes), { \"type\": \"executeJavascript\", \"script\": \"document.title\" } (results in actions.javascriptReturns), { \"type\": \"pdf\", \"format\": \"A4\" } (links in actions.pdfs) or { \"type\": \"perform\", \"action\": \"Click the Load more button\" } (a step in plain words, up to 5 browser steps on this page, never leaving the site; at most 5 per call). A read with actions costs 1 credit, the same as any page; the actions themselves add nothing. If an action fails, you still get the page as it stood, with a warning that names the action and says why.","minItems":1,"maxItems":50,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"wait"},"milliseconds":{"type":"integer","minimum":1,"maximum":60000}},"required":["type","milliseconds"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"wait"},"selector":{"type":"string","minLength":1}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"click"},"selector":{"type":"string","minLength":1},"all":{"type":"boolean","const":false}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"write"},"text":{"type":"string","minLength":1}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"press"},"key":{"type":"string","minLength":1,"maxLength":40}},"required":["type","key"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scroll"},"direction":{"default":"down","type":"string","enum":["up","down","left","right"]},"amount":{"anyOf":[{"type":"integer","minimum":1,"maximum":100000},{"type":"string","enum":["viewport","max"]}]},"maxScrolls":{"type":"integer","minimum":1,"maximum":50},"selector":{"type":"string","minLength":1}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"screenshot"},"fullPage":{"type":"boolean"},"quality":{"type":"integer","minimum":1,"maximum":100},"viewport":{"type":"object","properties":{"width":{"type":"integer","minimum":200,"maximum":3840},"height":{"type":"integer","minimum":200,"maximum":2160}},"required":["width","height"],"additionalProperties":false}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scrape"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"executeJavascript"},"script":{"type":"string","minLength":1,"maxLength":20000}},"required":["type","script"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"pdf"},"format":{"type":"string","enum":["Letter","Legal","Tabloid","Ledger","A0","A1","A2","A3","A4","A5","A6"]},"landscape":{"type":"boolean"},"scale":{"type":"number","minimum":0.1,"maximum":2}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"perform"},"action":{"type":"string","minLength":1,"maxLength":500}},"required":["type","action"],"additionalProperties":false}]}},"location":{"description":"Where to read the page from. The default is the United States.","type":"object","properties":{"country":{"description":"Two-letter country code to read the page from, such as DE or JP.","type":"string"},"languages":{"description":"Languages to ask the site for, best first, such as [\"de\", \"en\"]. Sent as Accept-Language. A read with languages is never answered from or saved to a stored copy.","minItems":1,"maxItems":5,"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"}}},"additionalProperties":false},"removeBase64Images":{"description":"Images inside the page that carry their data in the address (data:image) are dropped by default. Send false to keep them in markdown and html.","type":"boolean"},"blockAds":{"description":"Ads and trackers are not loaded when a page runs in a browser. Send false to load them.","type":"boolean"},"fastMode":{"description":"Send true to read the page without opening a browser: the answer comes sooner, but a page that needs a browser, or that refuses a plain request, comes back as an error instead of being retried. Ignored when the call needs a browser (actions, screenshot, waitFor, mobile, profile, network, branding).","type":"boolean"},"proxy":{"description":"auto: basic first, enhanced once if the site refuses. basic: one plain attempt. enhanced: the stronger read from the start. stealth is the same as enhanced. Same price.","type":"string","enum":["auto","basic","enhanced","stealth"]},"storeInCache":{"default":true,"description":"Send false to neither read nor keep a stored copy of this page.","type":"boolean"},"lockdown":{"description":"Send true to answer only from a stored copy of the page and never read it live, whatever its age. A page with no stored copy is notFound. The same as minAge 0.","type":"boolean"},"checkPromptInjection":{"description":"Send true to scan the page text for instructions aimed at an AI model before anything is built from it. A page that has them is refused with 403 promptInjectionDetected and costs nothing. The scan adds 4 credits when it runs; a page it cannot scan fully comes back with a warning and no charge.","type":"boolean"},"redactPII":{"description":"Send true, or an object, to hide personal data in the markdown and in everything made from it (summary, answers, highlights, json). Links, html and rawHtml are not changed. A page the model cannot scan is refused rather than returned unredacted.","anyOf":[{"type":"boolean"},{"type":"object","properties":{"mode":{"default":"accurate","description":"accurate finds names and places with the model and the rest by pattern. aggressive adds guesses that catch more and may hide a little too much. fast uses patterns only, so it finds no ordinary names or places.","type":"string","enum":["accurate","aggressive","fast"]},"entities":{"default":["PERSON","EMAIL","PHONE","LOCATION","FINANCIAL","SECRET"],"description":"What to hide: PERSON, EMAIL, PHONE, LOCATION, FINANCIAL, SECRET. All by default.","minItems":1,"type":"array","items":{"type":"string","enum":["PERSON","EMAIL","PHONE","LOCATION","FINANCIAL","SECRET"]}},"replaceStyle":{"default":"tag","description":"tag writes <EMAIL>, mask writes * for each character, remove deletes it.","type":"string","enum":["tag","mask","remove"]}},"additionalProperties":false,"description":"Options for redactPII."}]},"profile":{"description":"Read the page with the cookies and local storage that earlier calls saved under this name, kept for your account for 30 days after the last use. A call with a profile always loads the page in a browser, costs 1 credit, the same as any page, and is never answered from a stored copy. Only one call at a time can save to a profile.","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128,"description":"A name you choose, such as shop-login. Calls with the same name share state."},"saveChanges":{"default":true,"description":"Keep the cookies and local storage this read leaves behind for the next call with this name. Send false to read with the profile without changing it.","type":"boolean"}},"required":["name"],"additionalProperties":false},"zeroDataRetention":{"default":false,"description":"Send true to keep nothing from this call: no stored copy is read or made, and nothing from it is logged. Costs 1 credit more per page. Not with a screenshot.","type":"boolean"}}},"zeroDataRetention":{"default":false,"description":"Send true to keep nothing from this crawl: no stored copy is read or made, page results are held for one hour at most, and nothing is logged. Costs 1 credit more per page.","type":"boolean"},"webhook":{"description":"Where to be told about the job: a plain address, or { url } which gets a JSON POST when the job starts, for each finished page, and when the job ends. headers are sent with every call, metadata comes back in every call, and events picks which of started, page, action, completed, failed and cancelled to send (all by default). An agent run sends action for each step it takes, and page too. Every call is signed: read Stophy-Signature (t=<unix seconds>,v1=<hex>), where v1 is the HMAC-SHA256 of \"<t>.<body>\" with your webhook secret from webhook.secret. A call that gets no 2xx is sent again, up to 3 times. If your address answers slowly, a page event can carry only the page url. Read that page with the status call.","anyOf":[{"type":"string"},{"type":"object","properties":{"url":{"type":"string"},"headers":{"type":"object","propertyNames":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$"},"additionalProperties":{"type":"string","maxLength":1000}},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"events":{"minItems":1,"type":"array","items":{"type":"string","enum":["started","page","action","completed","failed","cancelled"]}}},"required":["url"],"additionalProperties":false}]}},"required":["url"],"$defs":{"__schema0":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema0"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}}]},"__schema1":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema1"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema1"}}]},"__schema2":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema2"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema2"}}]}},"additionalProperties":false},"example":{"url":"https://bun.com/docs","limit":2}},{"id":"crawl.params-preview","title":"Web Crawl Options From A Prompt","summary":"Turn a plain-language crawl request into the options crawl takes, without starting one","bestWhen":"Best to see what a crawl would do before starting it. Send the site's address and what you want, such as only the blog posts from this year. The answer holds the options to pass to crawl. A call that finds nothing to set is free.","method":"POST","path":"/v1/crawl/params-preview","credits":4,"maxCredits":4,"pricing":null,"keyless":false,"cacheTtlSeconds":0,"input":{"type":"object","properties":{"url":{"description":"The site to crawl, such as https://bun.com.","type":"string"},"prompt":{"type":"string","minLength":1,"maxLength":1000,"description":"What you want from the crawl, such as only the blog posts."}},"required":["url","prompt"],"additionalProperties":false},"example":null},{"id":"batch.scrape","title":"Web Batch","summary":"Scrape many pages in the background","bestWhen":"Best for a list of addresses you already have. It answers at once with an id; ask batch.scrape.status for the pages, or send webhook to be told as each one finishes.","method":"POST","path":"/v1/batch/scrape","credits":0,"maxCredits":30,"pricing":"1 credit a page, however it is reached. checkPromptInjection adds 4 credits when the scan runs, json with a schema or a prompt, summary, highlights, question, product, menu and changeTracking in json mode add 4 credits each when they return something. CSS rules and attributes add nothing. A PDF adds 1 credit for each page of text that comes back, so a PDF read with maxChars, offset or query is charged for the share of its pages that it returns, at least 1 page. Browser actions add nothing. An answer from a stored copy within maxAge costs 1 credit like any page. A page that comes back with a 404 or 410 status, or cannot be read, costs nothing. Each page is charged when it finishes. Starting the job is free","keyless":false,"cacheTtlSeconds":0,"input":{"type":"object","properties":{"urls":{"minItems":1,"type":"array","items":{"type":"string","maxLength":2048},"description":"The pages or PDFs to read. An address sent twice is read once."},"webhook":{"description":"Where to be told about the job: a plain address, or { url } which gets a JSON POST when the job starts, for each finished page, and when the job ends. headers are sent with every call, metadata comes back in every call, and events picks which of started, page, action, completed, failed and cancelled to send (all by default). An agent run sends action for each step it takes, and page too. Every call is signed: read Stophy-Signature (t=<unix seconds>,v1=<hex>), where v1 is the HMAC-SHA256 of \"<t>.<body>\" with your webhook secret from webhook.secret. A call that gets no 2xx is sent again, up to 3 times. If your address answers slowly, a page event can carry only the page url. Read that page with the status call.","anyOf":[{"type":"string"},{"type":"object","properties":{"url":{"type":"string"},"headers":{"type":"object","propertyNames":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$"},"additionalProperties":{"type":"string","maxLength":1000}},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"events":{"minItems":1,"type":"array","items":{"type":"string","enum":["started","page","action","completed","failed","cancelled"]}}},"required":["url"],"additionalProperties":false}]},"maxConcurrency":{"description":"Most pages read at once for this batch. We read at most 4 at once, so a larger number gives the same speed.","type":"integer","minimum":1,"maximum":100},"appendToId":{"description":"The id of a batch of yours that is still running: add urls to it instead of starting a new batch. The batch keeps its own options and webhook. Answers jobFinished when the batch is over.","type":"string","pattern":"^[A-Za-z0-9_-]{1,100}$"},"ignoreInvalidURLs":{"default":true,"description":"Skip addresses that are not public website URLs and list them in invalidURLs. Send false to refuse the whole batch instead.","type":"boolean"},"formats":{"description":"What to return: markdown (clean page text), summary (a short summary of the page), html (the cleaned page), rawHtml (the page as sent), audio and video (for a YouTube link: the audio track as an M4A file, or the video as an MP4 file, as a link that works for 1 hour), rawBase64 (the bytes the site sent, Base64 encoded, from a live read; metadata.contentType says what they are), links (every link on the page), images (every image address), screenshot (a link to a JPEG of the visible page, kept for 7 days), changeTracking (what changed in the markdown since your key last read this page with the same options, kept 30 days; add modes [\"git-diff\",\"json\"] with a schema or prompt to compare fields too), question (send { \"type\": \"question\", \"question\": \"...\" } to get answer, null when the page does not state one), product (title, brand, category, url, description and variants with price, sale, availability and images, or null) and menu (merchant, currency and sections of items with prices, or null) network (the JSON the page loaded while it rendered, up to 30 responses) and branding (the page's colors, fonts, typography, spacing, button and input styles, logo and brand images, read from how the page looks, with a field left out when the page does not show it). Send { \"type\": \"screenshot\", \"fullPage\": true } for the whole page. Send { \"type\": \"highlights\", \"query\": \"refund policy\" } for the passages that best match a query. Send { \"type\": \"json\", \"schema\": { \"type\": \"object\", \"properties\": { \"price\": { \"type\": \"number\" } } } } or { \"type\": \"json\", \"prompt\": \"the price and the stock\" } for fields filled from the page, each checked against it. Send { \"type\": \"json\", \"parser\": \"amazon-product\" } to get a site's own data as json instead of reading the page; GET /v1/parsers lists the parsers. Send { \"type\": \"json\", \"rules\": { \"title\": \"h1\", \"links\": { \"selector\": \"a\", \"type\": \"list\", \"output\": \"@href\" } } } to read the page with CSS rules and no model, at the page's own price. Send { \"type\": \"attributes\", \"selectors\": [{ \"selector\": \"a\", \"attribute\": \"href\" }] } for attribute values, returned in attributes. Without a parser or rules, json needs a schema or a prompt and is filled from the page. json with a schema or a prompt, summary, highlights, question, product, menu and changeTracking in json mode cost 4 credits more each when they return something. json with rules or a parser, and attributes, cost nothing more. A screenshot, network or branding read costs 1 credit, the same as any page. A PDF comes back as markdown only, and costs 1 credit more for each page of text that comes back. A CSV or an Excel .xlsx file comes back as markdown tables.","default":["markdown"],"minItems":1,"maxItems":20,"type":"array","items":{"anyOf":[{"type":"string","enum":["markdown","summary","html","rawHtml","rawBase64","links","images","network","branding","audio","video","screenshot","changeTracking","product","menu"]},{"type":"object","properties":{"type":{"type":"string","enum":["markdown","summary","html","rawHtml","rawBase64","links","images","network","branding","audio","video"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"changeTracking"},"modes":{"description":"git-diff returns a unified diff of the markdown. json compares the fields in schema or prompt between this read and the last one. Without modes you get git-diff.","maxItems":2,"type":"array","items":{"type":"string","enum":["git-diff","json"]}},"schema":{"description":"The fields to fill, as a JSON Schema (draft-07 or 2020-12) object with properties. Pydantic's model_json_schema() and zod's toJSONSchema() output work as they are. enum, const, anyOf, oneOf, nullable types, $ref with $defs, required, descriptions and any key names are read. Up to 100 top-level fields and 32 KB. A field the page does not state comes back null.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"prompt":{"description":"With json mode: what to compare, in plain words, such as the price and stock.","type":"string","minLength":1,"maxLength":10000},"tag":{"type":"null"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"question"},"question":{"type":"string","minLength":1,"maxLength":10000,"description":"A question to answer from the page, such as what the refund window is."}},"required":["type","question"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"product"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"menu"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"screenshot"},"fullPage":{"default":false,"description":"Capture the whole page from top to bottom instead of the visible part.","type":"boolean"},"quality":{"description":"JPEG quality from 1 to 100. The default is 70.","type":"integer","minimum":1,"maximum":100},"viewport":{"description":"The window size in pixels, such as { width: 390, height: 844 }.","type":"object","properties":{"width":{"type":"integer","minimum":200,"maximum":3840},"height":{"type":"integer","minimum":200,"maximum":2160}},"required":["width","height"],"additionalProperties":false}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"highlights"},"query":{"type":"string","minLength":1,"maxLength":10000,"description":"What you are looking for on the page, such as refund policy."},"count":{"default":5,"description":"How many passages to return, best match first.","type":"integer","minimum":1,"maximum":20}},"required":["type","query"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"json"},"parser":{"description":"Read the page with a named parser, which gives the site's own data as json. The url must be the kind of page the parser reads. Parsers are the only way to read some sites. GET /v1/parsers lists them.","type":"string"},"options":{"description":"Only with parser: extra inputs for it, such as { \"page\": 2 } for the next page of results or { \"minRating\": 4.5 } for a filter. GET /v1/parsers lists what each parser accepts.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema1"}},"schema":{"description":"The fields to fill, as a JSON Schema (draft-07 or 2020-12) object with properties. Pydantic's model_json_schema() and zod's toJSONSchema() output work as they are. enum, const, anyOf, oneOf, nullable types, $ref with $defs, required, descriptions and any key names are read. Up to 100 top-level fields and 32 KB. A field the page does not state comes back null.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"prompt":{"description":"What to pull from the page in plain words, such as the version and the release date.","type":"string","minLength":1,"maxLength":10000},"rules":{"description":"Read the page with CSS rules instead of a model, no extra fee. Each field is a selector such as \"h1\" (the first match's text), \"a@href\" (an attribute) or { \"selector\": \"li\", \"type\": \"list\", \"output\": \"text\" | \"html\" | \"@attribute\" | { nested fields } }. A missing item is null and an unmatched list is []. Relative links become absolute. Up to 100 fields, 5 levels deep. Not with schema, prompt or parser.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema2"}},"checkPromptInjection":{"description":"Deprecated: send checkPromptInjection at the top level of the call.","type":"boolean"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"attributes"},"selectors":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"selector":{"type":"string","minLength":1},"attribute":{"type":"string","minLength":1,"maxLength":100}},"required":["selector","attribute"],"additionalProperties":false},"description":"The elements and attributes to read, such as { selector: 'a.buy', attribute: 'href' }."}},"required":["type","selectors"],"additionalProperties":false}]}},"onlyMainContent":{"default":true,"description":"Keep only the page's main content, without menus, headers, footers and ads.","type":"boolean"},"onlyCleanContent":{"description":"Send true to have a model remove what onlyMainContent leaves behind in the markdown: cookie banners, ads, share widgets, breadcrumbs, sign-up prompts, comment prompts and related-article lists. It only removes whole paragraphs and lists; it never rewrites or adds text, and code blocks are always kept. Skipped with a warning when the page is too long to clean or the model does not answer. Not with zeroDataRetention. Summary, answers and highlights are made from the cleaned markdown.","type":"boolean"},"includeTags":{"description":"Keep only the parts of the page that match these CSS selectors, such as article or .price. When set, onlyMainContent is not applied.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"excludeTags":{"description":"Remove the parts of the page that match these CSS selectors, such as .comments.","minItems":1,"type":"array","items":{"type":"string","minLength":1}},"maxAge":{"description":"Accept a stored answer up to this many milliseconds old, at most 30 days. Without it, 2 days, or less for a site whose pages change often, and a copy up to twice that age (at most 7 days) comes back at once as stale while a fresh read runs. 0 always reads the page live. metadata.cacheState says which one you got.","type":"integer","minimum":0,"maximum":9007199254740991},"minAge":{"description":"Answer only from a stored copy that is at least this many milliseconds old, and never read the page live. 0 accepts any stored copy. A page with no such copy is notFound.","type":"integer","minimum":0,"maximum":9007199254740991},"headers":{"description":"Extra request headers to send to the site, such as { \"x-plan\": \"pro\" }. A read with headers is never answered from or saved to a stored copy.","type":"object","propertyNames":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$"},"additionalProperties":{"type":"string","maxLength":2000,"pattern":"^[\\t\\x20-\\x7e]*$"}},"waitFor":{"description":"Extra milliseconds to wait before reading, up to 60000, for pages that load their content late. To wait for an element, add a wait action with a selector. A read that waits costs 1 credit, the same as any page.","type":"integer","minimum":0,"maximum":60000},"mobile":{"description":"Read the page as a phone would: a phone-sized screen and the mobile version of the site. The page loads in a browser.","type":"boolean"},"skipTlsVerification":{"description":"Send true to read a page whose certificate is expired, self-signed or for another name. The read is not private against someone between us and the site.","type":"boolean"},"timeout":{"default":60000,"description":"How long to keep trying, in milliseconds, from 1 second to 5 minutes; 60 seconds by default. A page that needs a browser needs at least 5 seconds, and pages behind a bot check can need 10 to 30 seconds the first time. A read that runs out of time is an error and costs nothing.","type":"integer","minimum":1000,"maximum":300000},"parsers":{"description":"Only the pdf parser exists. Send \"pdf\" or { \"type\": \"pdf\", mode, maxPages, pages, blocks, pageMarkers } with the same meaning as in parse. Without mode a PDF is read as auto: from its text layer, and from the picture of any page that has no text. fast reads the text layer only, and ocr reads the picture of every page, up to 20 pages. Each page of text that comes back costs 1 credit. Pictures are read only with an API key.","minItems":1,"type":"array","items":{"anyOf":[{"type":"string","const":"pdf"},{"type":"object","properties":{"type":{"type":"string","const":"pdf"},"mode":{"description":"fast reads the text layer only. auto (the default) reads the text layer and reads the picture of any page that has none. ocr reads the picture of every page.","type":"string","enum":["fast","auto","ocr"]},"maxPages":{"description":"Read at most this many pages, up to 500, which is also the default.","type":"integer","minimum":1,"maximum":500},"pages":{"description":"Send true to also get each page's markdown in pages, as { pageNumber, markdown }. No extra charge.","type":"boolean"},"blocks":{"description":"Send true to also get the page's layout in blocks: each title, section header or run of text, with its page, reading order, position on the page (bbox as left, top, right, bottom from 0 to 1) and where its text sits in that page's markdown (span, as in pages). Tables, figures and formulas are not told apart. A page read from its picture is one block. No extra charge.","type":"boolean"},"pageMarkers":{"description":"Send true to mark page breaks in the markdown: pages are joined with \"---\" and a <!-- page N --> line, where N is the page that follows. No extra charge.","type":"boolean"}},"required":["type"],"additionalProperties":false}]}},"actions":{"description":"Up to 50 steps to run on the page, in order, before reading it: { \"type\": \"wait\", \"milliseconds\": 500 } (up to 60 seconds), { \"type\": \"wait\", \"selector\": \".results\" }, { \"type\": \"click\", \"selector\": \"button.more\" }, { \"type\": \"write\", \"text\": \"tides\" }, { \"type\": \"press\", \"key\": \"Enter\" }, { \"type\": \"scroll\", \"direction\": \"down\" } (also up, left or right; amount is pixels, \"viewport\" or \"max\"; maxScrolls 1 to 50; selector scrolls an inner container; \"max\" keeps scrolling until the page stops growing, for feeds that load as you go), { \"type\": \"screenshot\", \"fullPage\": true } (links come back in actions.screenshots), { \"type\": \"scrape\" } (the page at that point, in actions.scrapes), { \"type\": \"executeJavascript\", \"script\": \"document.title\" } (results in actions.javascriptReturns), { \"type\": \"pdf\", \"format\": \"A4\" } (links in actions.pdfs) or { \"type\": \"perform\", \"action\": \"Click the Load more button\" } (a step in plain words, up to 5 browser steps on this page, never leaving the site; at most 5 per call). A read with actions costs 1 credit, the same as any page; the actions themselves add nothing. If an action fails, you still get the page as it stood, with a warning that names the action and says why.","minItems":1,"maxItems":50,"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","const":"wait"},"milliseconds":{"type":"integer","minimum":1,"maximum":60000}},"required":["type","milliseconds"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"wait"},"selector":{"type":"string","minLength":1}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"click"},"selector":{"type":"string","minLength":1},"all":{"type":"boolean","const":false}},"required":["type","selector"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"write"},"text":{"type":"string","minLength":1}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"press"},"key":{"type":"string","minLength":1,"maxLength":40}},"required":["type","key"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scroll"},"direction":{"default":"down","type":"string","enum":["up","down","left","right"]},"amount":{"anyOf":[{"type":"integer","minimum":1,"maximum":100000},{"type":"string","enum":["viewport","max"]}]},"maxScrolls":{"type":"integer","minimum":1,"maximum":50},"selector":{"type":"string","minLength":1}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"screenshot"},"fullPage":{"type":"boolean"},"quality":{"type":"integer","minimum":1,"maximum":100},"viewport":{"type":"object","properties":{"width":{"type":"integer","minimum":200,"maximum":3840},"height":{"type":"integer","minimum":200,"maximum":2160}},"required":["width","height"],"additionalProperties":false}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"scrape"}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"executeJavascript"},"script":{"type":"string","minLength":1,"maxLength":20000}},"required":["type","script"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"pdf"},"format":{"type":"string","enum":["Letter","Legal","Tabloid","Ledger","A0","A1","A2","A3","A4","A5","A6"]},"landscape":{"type":"boolean"},"scale":{"type":"number","minimum":0.1,"maximum":2}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"perform"},"action":{"type":"string","minLength":1,"maxLength":500}},"required":["type","action"],"additionalProperties":false}]}},"location":{"description":"Where to read the page from. The default is the United States.","type":"object","properties":{"country":{"description":"Two-letter country code to read the page from, such as DE or JP.","type":"string"},"languages":{"description":"Languages to ask the site for, best first, such as [\"de\", \"en\"]. Sent as Accept-Language. A read with languages is never answered from or saved to a stored copy.","minItems":1,"maxItems":5,"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$"}}},"additionalProperties":false},"removeBase64Images":{"description":"Images inside the page that carry their data in the address (data:image) are dropped by default. Send false to keep them in markdown and html.","type":"boolean"},"blockAds":{"description":"Ads and trackers are not loaded when a page runs in a browser. Send false to load them.","type":"boolean"},"fastMode":{"description":"Send true to read the page without opening a browser: the answer comes sooner, but a page that needs a browser, or that refuses a plain request, comes back as an error instead of being retried. Ignored when the call needs a browser (actions, screenshot, waitFor, mobile, profile, network, branding).","type":"boolean"},"proxy":{"description":"auto: basic first, enhanced once if the site refuses. basic: one plain attempt. enhanced: the stronger read from the start. stealth is the same as enhanced. Same price.","type":"string","enum":["auto","basic","enhanced","stealth"]},"storeInCache":{"default":true,"description":"Send false to neither read nor keep a stored copy of this page.","type":"boolean"},"lockdown":{"description":"Send true to answer only from a stored copy of the page and never read it live, whatever its age. A page with no stored copy is notFound. The same as minAge 0.","type":"boolean"},"checkPromptInjection":{"description":"Send true to scan the page text for instructions aimed at an AI model before anything is built from it. A page that has them is refused with 403 promptInjectionDetected and costs nothing. The scan adds 4 credits when it runs; a page it cannot scan fully comes back with a warning and no charge.","type":"boolean"},"redactPII":{"description":"Send true, or an object, to hide personal data in the markdown and in everything made from it (summary, answers, highlights, json). Links, html and rawHtml are not changed. A page the model cannot scan is refused rather than returned unredacted.","anyOf":[{"type":"boolean"},{"type":"object","properties":{"mode":{"default":"accurate","description":"accurate finds names and places with the model and the rest by pattern. aggressive adds guesses that catch more and may hide a little too much. fast uses patterns only, so it finds no ordinary names or places.","type":"string","enum":["accurate","aggressive","fast"]},"entities":{"default":["PERSON","EMAIL","PHONE","LOCATION","FINANCIAL","SECRET"],"description":"What to hide: PERSON, EMAIL, PHONE, LOCATION, FINANCIAL, SECRET. All by default.","minItems":1,"type":"array","items":{"type":"string","enum":["PERSON","EMAIL","PHONE","LOCATION","FINANCIAL","SECRET"]}},"replaceStyle":{"default":"tag","description":"tag writes <EMAIL>, mask writes * for each character, remove deletes it.","type":"string","enum":["tag","mask","remove"]}},"additionalProperties":false,"description":"Options for redactPII."}]},"profile":{"description":"Read the page with the cookies and local storage that earlier calls saved under this name, kept for your account for 30 days after the last use. A call with a profile always loads the page in a browser, costs 1 credit, the same as any page, and is never answered from a stored copy. Only one call at a time can save to a profile.","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128,"description":"A name you choose, such as shop-login. Calls with the same name share state."},"saveChanges":{"default":true,"description":"Keep the cookies and local storage this read leaves behind for the next call with this name. Send false to read with the profile without changing it.","type":"boolean"}},"required":["name"],"additionalProperties":false},"zeroDataRetention":{"default":false,"description":"Send true to keep nothing from this call: no stored copy is read or made, and nothing from it is logged. Costs 1 credit more per page. Not with a screenshot.","type":"boolean"},"linkStyle":{"default":"inline","description":"How links appear in the markdown. inline keeps [text](address). numbered writes Pricing⟨3⟩ and lists each address once at the end. none keeps only the link text, which makes link-heavy pages 10 to 70% shorter; ask for the links format to get the addresses.","type":"string","enum":["inline","numbered","none"]},"maxChars":{"description":"Cut the markdown at this many characters; isTruncated says when that happened and nextOffset where to read on. With query, how much of the page to keep, 8000 by default.","type":"integer","minimum":500,"maximum":1000000},"query":{"description":"What you are looking for on the page, such as refund window. A page longer than maxChars (8000 by default) comes back as the passages that match, in page order, each with the text around it and its table header; a shorter page comes back whole. Costs nothing extra, and a PDF is charged for the share of its pages that comes back. Not with offset.","type":"string","minLength":1,"maxLength":10000}},"required":["urls"],"$defs":{"__schema0":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema0"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}}]},"__schema1":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema1"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema1"}}]},"__schema2":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema2"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema2"}}]}},"additionalProperties":false},"example":{"urls":["https://bun.com/docs/runtime/bunfig","https://bun.com/docs/runtime/env"]}},{"id":"agent","title":"Web Agent","summary":"Give it a task and it searches, reads pages and fills your fields, with a quote for each","bestWhen":"Best for a question that needs several pages, like the pricing tiers of a few products or the CEO and headquarters city of a list of startups. Send prompt, and schema for the fields you want (any JSON Schema), and urls to start from. It answers at once with an id, threadId and threadTurn; ask agent.status for the result. The agent searches, reads pages and checks every value against the page text, in up to 3 rounds. It is charged step by step at the normal price of each search and page, plus 4 credits for each planning or answering step, and stops before maxCredits. A run that cannot finish inside maxCredits fails with stopReason credit_limit_reached and what it found in partial; the credits it spent are still charged. To ask a follow-up, send the threadId from agent.status.","method":"POST","path":"/v1/agent","credits":0,"maxCredits":2500,"pricing":"each search and page at its normal price, plus 4 credits for each planning or answering step that returns something, never more than maxCredits. Each step is charged when it finishes. Starting the run is free","keyless":false,"cacheTtlSeconds":0,"input":{"type":"object","properties":{"prompt":{"type":"string","minLength":1,"maxLength":10000,"description":"What to find, in plain words, such as the pricing tiers of Pinecone, Qdrant and Weaviate, or the CEO and headquarters city of each of these startups."},"urls":{"description":"Pages to start from, up to 20. An address with * in it, such as https://qdrant.tech/blog/*, is expanded from the site's own page list, up to 10 pages. Without urls the agent searches the web.","minItems":1,"maxItems":20,"type":"array","items":{"type":"string","maxLength":2048}},"schema":{"description":"The fields to fill, as a JSON Schema (draft-07 or 2020-12) object with properties. Pydantic's model_json_schema() and zod's toJSONSchema() output work as they are. enum, const, anyOf, oneOf, nullable types, $ref with $defs, required, descriptions and any key names are read. Up to 100 top-level fields and 32 KB. A field the page does not state comes back null.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"maxCredits":{"default":2500,"description":"The most credits this run may spend. Default 2500. Every step is checked against what is left before it runs, so the run never goes over. A run that cannot finish inside it fails with stopReason credit_limit_reached and what it found in partial. The credits it already spent are charged.","type":"number","exclusiveMinimum":0},"includeSources":{"default":true,"description":"Send false to leave sources out of the answer. They cost nothing.","type":"boolean"},"model":{"default":"spark-2","description":"Any model name is accepted, such as spark-2, spark-1-mini, spark-1-pro or spark-1-fast. Every name runs the same agent, and the name you send is echoed back.","type":"string","minLength":1,"maxLength":100},"mode":{"description":"extract (the default) fills your fields on every turn. chat lets a follow-up that asks for no new data get a short reply in message, for 4 credits, instead of a new run. Needs threadId. A follow-up that omits mode keeps the thread's mode.","type":"string","enum":["extract","chat"]},"effort":{"description":"How many search-and-read rounds the agent may take: low 1, medium 2, high 3 (the default). A follow-up that omits effort keeps the thread's.","type":"string","enum":["low","medium","high"]},"location":{"description":"The country every search and page read goes out from, and results are localized to. A follow-up that omits location keeps the thread's.","type":"object","properties":{"country":{"description":"Two-letter country code, such as DE or JP.","type":"string","minLength":2,"maxLength":2}},"required":["country"]},"strictConstrainToURLs":{"description":"Send true to read only the pages in urls, with no searching. Needs urls, or a thread that has them.","type":"boolean"},"threadId":{"description":"Ask a follow-up in the same thread: send the threadId an earlier run returned. The run sees the earlier question and answer, and omitted urls, schema, effort, mode and location carry over.","type":"string","pattern":"^[A-Za-z0-9_-]{1,100}$"},"zeroDataRetention":{"description":"Send true to keep nothing from this run: the prompt, steps and result are held for one hour at most and nothing is logged. Each page read costs 1 credit more. Cannot be sent with threadId.","type":"boolean"},"safe":{"description":"Send true to hide explicit results from every web search in the run. Pages in urls and pages the agent opens are not filtered. A follow-up that omits safe keeps the thread's.","type":"boolean"},"auditMetadata":{"description":"Who made the request, kept with the run and read back by agent.status.","type":"object","properties":{"username":{"type":"string","maxLength":1024}},"required":["username"],"additionalProperties":false},"webhook":{"description":"Where to be told about the job: a plain address, or { url } which gets a JSON POST when the job starts, for each finished page, and when the job ends. headers are sent with every call, metadata comes back in every call, and events picks which of started, page, action, completed, failed and cancelled to send (all by default). An agent run sends action for each step it takes, and page too. Every call is signed: read Stophy-Signature (t=<unix seconds>,v1=<hex>), where v1 is the HMAC-SHA256 of \"<t>.<body>\" with your webhook secret from webhook.secret. A call that gets no 2xx is sent again, up to 3 times. If your address answers slowly, a page event can carry only the page url. Read that page with the status call.","anyOf":[{"type":"string"},{"type":"object","properties":{"url":{"type":"string"},"headers":{"type":"object","propertyNames":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$"},"additionalProperties":{"type":"string","maxLength":1000}},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}},"events":{"minItems":1,"type":"array","items":{"type":"string","enum":["started","page","action","completed","failed","cancelled"]}}},"required":["url"],"additionalProperties":false}]}},"required":["prompt"],"$defs":{"__schema0":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"array","items":{"$ref":"#/$defs/__schema0"}},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/$defs/__schema0"}}]}},"additionalProperties":false},"example":{"prompt":"What is the name of the configuration file this page describes?","urls":["https://bun.com/docs/runtime/bunfig"],"schema":{"type":"object","properties":{"file":{"type":"string"}}},"maxCredits":10}},{"id":"webhook.secret","title":"Webhook Secret","summary":"Read or replace the secret that signs your webhook calls","bestWhen":"Use the secret to check Stophy-Signature on a webhook call: compute the HMAC-SHA256 of \"<t>.<body>\" and compare it with v1, then reject a call whose t is more than a few minutes old. Send rotate: true to get a new secret; the old one stops signing at once, so deploy the new one first or accept both for a while.","method":"POST","path":"/v1/webhook/secret","credits":0,"maxCredits":0,"pricing":null,"keyless":false,"cacheTtlSeconds":0,"input":{"type":"object","properties":{"rotate":{"default":false,"description":"Send true to replace the secret with a new one.","type":"boolean"}},"additionalProperties":false},"example":null}]}