# getclean > getclean is the data layer for research agents. Give it a URL, a file or a question, and get back what the source says, exactly, where it says it, as of when, what to trust, what changed and what it cost. > ## Agent Instructions > getclean's own MCP server is at https://mcp.getclean.ai/mcp. The /mcp path of this docs site is Mintlify's search over these pages, not getclean. > Every answer of the API opens with outcome. A page that could not be read is a record whose outcome says why, never an HTTP error; read outcome before anything else. > The API's contract is the OpenAPI 3.1 file at https://docs.getclean.ai/openapi.yaml; the SDKs are generated from it. > The product's name is written getclean, in lower case. - [Getclean](https://docs.getclean.ai/index.md): The data layer for research agents. It fetches web pages and documents, searches the web and specialist sources, and returns clean, structured content that you can cite. - [From a question to a checked report](https://docs.getclean.ai/start/how-it-fits.md): A research run has 5 steps: find sources, read them, find the evidence, cite it, and check the work. Each step has its call, and each call returns what the next step needs. - [Find, read, and cite a source in 3 calls](https://docs.getclean.ai/start/quickstart.md): Install an SDK and take one question from nothing to a passage you can cite. A search finds the source, a highlight finds the passage that bears on your question, and one more call opens that passage again. - [Authenticate a request](https://docs.getclean.ai/start/authentication.md): Send an API key or an access token as a bearer credential with every call. Each key has a list of scopes, and a call outside that list is refused before any work is done or charged. - [Give an agent a whole research run in 5 tools](https://docs.getclean.ai/start/agent-tools.md): Wrap 5 calls as tools and an agent can do a whole research run: find sources, read them in parts, find the passages for its questions, and cite them. This page has the tool definitions and the code that runs them. - [Ask one question in 20 wordings](https://docs.getclean.ai/find/search-across-sources.md): Send one question with other wordings of it, in any language. The search runs them all on the web and on specialist datasources and returns one ranked list. Each result says which wording found it, and where. - [Get one ranked list from the web and from specialist datasources](https://docs.getclean.ai/find/where-you-can-search.md): A search runs on the web and on up to 10 datasources at once and returns one ranked list. Name the datasources, or let the search choose the ones that fit the question. The catalog says what each one covers. - [Put primary sources first](https://docs.getclean.ai/find/rank-by-source.md): Every search result says what kind of source it is: who publishes it, whether it is primary, independent, and reviewed. Rank by those facts, filter by them, or tell the ranking in your own words what matters. - [Find the exact paper, case, or company by its identifier](https://docs.getclean.ai/find/identifiers.md): Search by an exact code in place of words: a DOI, a docket number, a ticker, a registry number, and 12 more schemes. The search goes to the datasources that can look the code up, and each result says which codes it matches. - [See what a search covered and what it missed](https://docs.getclean.ai/find/search-receipt.md): Every search returns a receipt: which datasources ran, with which wordings and filters, how many results each found, what was dropped and why, and what was asked but not searched. - [Search and get the evidence in one call](https://docs.getclean.ai/find/search-and-read.md): Let a search fetch its first results in the same call. Each comes back as a record with its outline, the passages that bear on your questions, or your own fields filled, before an agent has read one page. - [Ask 20 questions in one call](https://docs.getclean.ai/find/many-searches-at-once.md): Send up to 20 questions in one call, each with its own wordings, country, and purpose. The questions share one set of filters and one spending limit, and the response opens with a tally of how they ended. - [Fetch what a page says, not what surrounds it](https://docs.getclean.ai/read/page-as-published.md): Fetch a page at a URL and get its main content with every heading, table, and link as the page has them, without the navigation and the advertising. The response names what was left out and what the page hides. - [Turn PDFs, Office files, and scans into evidence you can cite by page](https://docs.getclean.ai/read/pdfs-scans-and-documents.md): Send a file or its address and get the same record a web page gives: the content with its sections, its tables, and its page numbers. A scanned page is read from its picture, and the response says how sure the reading is. - [Read the 2 sections you need from a 300-page document](https://docs.getclean.ai/read/long-documents.md): Get the outline of a source before any of its text: one row for each section, with its id, its title, and its size. Then read only the sections you need, by id. The rest stays in the record. - [Get every table, cell by cell](https://docs.getclean.ai/read/tables-and-blocks.md): Ask a record for its tables and get each one as rows of cells, with its merged cells and its header rows. A figure in your report can then name the row and the column it came from. - [Follow a page to the documents it links to](https://docs.getclean.ai/read/links.md): List every link of a stored page with its kind and its place on the page. Take the links to files, and fetch each file as a record. A deadline inside a linked PDF is then read, not missed. - [Time machine: read a page as it was on a past day](https://docs.getclean.ai/read/time-machine.md): Name a day, and fetch the page as an archive stored it on or before that day. The response says when the copy was made and when the next one was, so you can step through a page's past and find the day a sentence changed. - [Fetch 20 sources at once and know what came back before you read a word](https://docs.getclean.ai/read/many-pages-at-once.md): Send up to 20 addresses in one call and get one record for each. The response opens with a tally of how the fetches ended, so your code knows the state of the whole batch before it reads one record. - [Fetch a source once, then read it as often as you need](https://docs.getclean.ai/read/again-for-free.md): Every fetch and every upload is stored as a record. Read it again in another format, at another size, or as the whole page, without a second visit to the source. Every such read is from the same copy. - [Highlight the evidence for each question](https://docs.getclean.ai/read/highlight-passages-and-answers.md): Send up to 5 phrases or questions with a fetch, or to a stored record. Each place that matches comes back with its section, its block, and its page, and with a mark in the text that says which question found it. - [Fill your fields, each with the words it came from](https://docs.getclean.ai/read/extract-fields-with-citations.md): Send your own fields as a JSON Schema and get them filled from a source. A value comes only where the source states it, with the words it was taken from. An empty field says why it is empty. - [Summarize a source before you read it](https://docs.getclean.ai/read/summarize-a-source.md): Get a summary of a source in at most 1,500 characters, in the source's own language. A model writes it, and the response says so. Use it to choose what to read in full. - [Cite the passage, not the page](https://docs.getclean.ai/read/cite-the-passage.md): A citation that names the page leaves the reader to search it. Cite the passage: the record, the block, the printed page, and the words. Anyone can open it again, and a later check can tell whether the source still says it. - [Check every sentence of a draft against its source](https://docs.getclean.ai/read/check-a-draft.md): Before a report goes out, send its sentences against the records they cite. A quote that is in the source word for word is confirmed without a model. A sentence that nothing in the source supports comes back as not found. - [Find the one cell that changed](https://docs.getclean.ai/read/track-what-changed.md): Send a record's fingerprint with the next fetch to learn whether a source changed. Compare 2 records to get every change, block by block and cell by cell, with the text before and after. - [Keep proof of what a page showed](https://docs.getclean.ai/read/proof.md): Fetch a page with the bytes its server sent and a picture of the whole page, each with a digest. With the record's time and fingerprint, they show later what the page said on the day you read it. - [Deep research with a source for every claim](https://docs.getclean.ai/use-cases/deep-research.md): Build a research agent whose report can be checked. Every sentence names the passage it rests on, every empty cell says why it is empty, and every search is stored with its receipt. The example compares the AI strategies of 60 countries. - [RAG that cites the passage, not the page](https://docs.getclean.ai/use-cases/rag-citations.md): Build a retrieval index from blocks that come with ids. Each chunk is one whole paragraph or one whole table, each answer cites its passage, and only the blocks that changed are indexed again. - [Reinforcement learning for research agents](https://docs.getclean.ai/use-cases/reinforcement-learning.md): Train and test research agents in an environment that stays the same: the same text in every rollout, time fixed on one day, actions with consequences, feedback after every action, and rewards that a script computes without a judge model. - [Figures from filings, each traced to its cell](https://docs.getclean.ai/use-cases/filings.md): Take revenue, margin, and debt from annual reports as figures that name their table, their row, and their column. Tell what a company reports about itself from what others estimate, and find a figure that was restated. - [A time machine for backtests](https://docs.getclean.ai/use-cases/backtests.md): Build a dataset in which every page is read from the last archive copy made on or before its trade date. Each row has the time its copy was made, a page without a copy is marked and not guessed, and model validation can check every row. - [Covenants and the definitions they depend on](https://docs.getclean.ai/use-cases/credit-agreements.md): Read a 300-page credit agreement by its outline, mark every covenant, follow each defined term to its definition 200 pages away, and quote each clause with the page that is printed on it. - [Contract review that tells a missing clause from an unread page](https://docs.getclean.ai/use-cases/contract-review.md): Review 300 supplier contracts against one checklist. A clause that is found comes with its words and its page. A clause that is not found says whether the contract lacks it or a page could not be read. - [Case citations checked before filing](https://docs.getclean.ai/use-cases/case-citations.md): Before a brief is filed, look up every case it cites by its docket number or its reporter citation, and match every quotation against the opinion. A citation to a case that does not exist is found by your agent, not by the court. - [Regulatory change, down to the sentence](https://docs.getclean.ai/use-cases/regulatory-change.md): Watch 60 official pages each night. A page whose text is the same asks nothing of your team. A page that changed comes with the sentence or the table cell that changed, before and after. - [Counterparty screening: what the company says, and what others say](https://docs.getclean.ai/use-cases/screening.md): Screen a company by its registry codes, in the languages of its country. Each result says whether its source is the company or is independent of it, and a story printed on 30 sites counts once. - [Systematic reviews: the search writes its own PRISMA record](https://docs.getclean.ai/use-cases/systematic-reviews.md): Run one question in every wording on the datasources of your protocol. The response has, for each datasource, the date, the wordings, and the counts, with the copies removed and each dropped record's reason, written up in PRISMA form. - [Values from a paper's tables, not its abstract](https://docs.getclean.ai/use-cases/papers.md): Find a paper by its DOI and take its results from the table they are printed in, cell by cell, with the formula of its method as TeX. Each value in your comparison names its table, its row, and its page. - [Policy wordings compared clause by clause](https://docs.getclean.ai/use-cases/policy-wordings.md): Put the same 5 questions to the policy wording of each insurer. Each wording returns the clauses that bear on each question, with their section and printed page, so 3 wordings line up question by question. - [Scanned claim files with a confidence on every value](https://docs.getclean.ai/use-cases/claim-files.md): Upload a scanned claim file and get your fields filled from it. Each value comes with the words it was read from, its page, and a number for how sure the reading is, so a person checks only the values that need it. - [Competitor pricing, compared cell by cell](https://docs.getclean.ai/use-cases/competitor-pricing.md): Read a competitor's pricing page as a visitor from each of your markets sees it. The table comes cell by cell, a change comes as the one cell that changed, and a picture of the page shows what the price was that day. - [Tenders and the addenda that move their deadlines](https://docs.getclean.ai/use-cases/tenders.md): Follow a tender page to every file it links to, and read each file. When an addendum appears, your agent knows that it is new, reads it, and finds the sentence that moves the closing date. - [A claim traced to its first source](https://docs.getclean.ai/use-cases/fact-checking.md): Search for a claim and get the oldest source first. A story that 38 sites printed is one result with its copies counted, primary sources come before the reports on them, and a page can be read as it was before an edit. - [Scanned public records, searched with the page as proof](https://docs.getclean.ai/use-cases/public-records.md): Upload a release of scanned records and find a name on every page that has it. Each place comes with its page number, a number for how sure the reading is, and a picture of the page to check it against. - [Answers from official pages only](https://docs.getclean.ai/use-cases/official-answers.md): Build an assistant for residents that searches only the sites you name, returns the passage of the official page that answers, and shows its date. A forum post cannot enter an answer, because only the sites you name are searched. - [Supplier certificates checked at the body that issued them](https://docs.getclean.ai/use-cases/supplier-checks.md): Read the certificate that a supplier sends, and look its number up in the register of the body that issued it. The result says what the register states about the certificate, not what the PDF claims. - [Emissions data with a source for every cell](https://docs.getclean.ai/use-cases/esg-data.md): Fill one template from 300 sustainability reports, 20 in a call. Each cell comes with the words and the page it was taken from, and an empty cell says whether the company does not report the figure or the page was not read. - [Why research agents need a data layer](https://docs.getclean.ai/understand/why-a-data-layer.md): A data layer gives an agent, as data, what a person sees on a page: which part is the article, which heading a number is under, who the publisher is. Each claim of the agent's report can then be checked at its passage. - [Records](https://docs.getclean.ai/understand/records.md): A record is the stored copy of one source at one moment, made by a fetch or an upload. Every later call reads that copy, so every read sees the same text. A record is stored for 48 hours after its last use, and for at most 30 days. - [Sections and blocks](https://docs.getclean.ai/understand/sections-and-blocks.md): Every part of a record has an address. A section is a heading with everything under it, and a block is one unit of content, such as a paragraph, a table, or an image. A passage is cited by its block, its page, and its words. - [Source profiles](https://docs.getclean.ai/understand/source-profiles.md): A source profile says what a source is: the kind of its publisher, whether it is a primary source, whether it is independent of the subject, and what review it states. It has facts and no score. - [Repeatable output and model steps](https://docs.getclean.ai/understand/repeatability.md): The content, the outline, and the places of a source are the same on every read. A model works only in steps that each response names, and one switch turns all of them off. - [Hidden text](https://docs.getclean.ai/understand/hidden-text.md): Some text on a web page cannot be seen by a person who reads it. It can be written for a model, as an instruction. Such text comes back apart from the content, with the way it was hidden. - [Outcomes and notices](https://docs.getclean.ai/understand/outcomes-and-notices.md): Every record starts with its outcome: what happened at the source, and what can work next. A page that could not be read is still a record, and its reason says what happened. - [Errors](https://docs.getclean.ai/understand/errors.md): An error is the API's response to a request that it refused or could not run. It says who has to act, whether sending the request again can help, and what to change, as data that a program can act on. - [Glossary of getclean terms](https://docs.getclean.ai/understand/glossary.md): Each term of the getclean docs with its one meaning, such as record, source, datasource, section, block, highlight, outline, outcome, notice, and fingerprint. - [What each call costs](https://docs.getclean.ai/start/pricing.md): Calls are charged in 7 units, such as one unit for a fetch and one for each model step. Reading a stored record costs nothing, and neither does a fetch that failed. Every charged response says what it cost. - [Set a spending limit that no call can pass](https://docs.getclean.ai/understand/costs-and-budgets.md): Set the most that one call can cost with max_cost. The call does what fits under the limit, says what it left out, and never spends more. A key and a run can have budgets of their own. - [Size limits, rate limits, and time limits](https://docs.getclean.ai/understand/limits.md): The size limits of requests and responses, the rate limits of a key, and the time limits of calls, in one place. One call, get_limits, returns the values that apply to your key. - [Changelog](https://docs.getclean.ai/changelog.md): Every change to the getclean API, newest first, under its version. Version 1.0.0 is the first entry. The page has an RSS feed, so you can follow new entries without coming back. - [API reference](https://docs.getclean.ai/api-reference/overview.md): The getclean API at api.getclean.ai has 22 operations under /v1, takes a bearer key on every request, and answers with what happened before anything else. This page lists every operation, the rules they all share, and the headers you send and get back. - [Fetch contents](https://docs.getclean.ai/api-reference/fetch-contents.md): Fetch a web page or a document at a URL. You get its main content with the structure intact, in the formats you ask for, the map of its sections, the facts of the source, a fingerprint and the price, as one record that is kept for later reads. - [Upload contents](https://docs.getclean.ai/api-reference/upload-contents.md): Read a document you hold, or one at a URL that needs more time than a fetch gives. You get the same record a fetch makes, the content with its structure intact, the map of its sections, the facts of the source, a fingerprint and the price, with `pages` saying how many pages were read, which failed a… - [Get job](https://docs.getclean.ai/api-reference/get-job.md): Read a job, or wait for it to finish, free. The answer comes at the final state or when `wait_seconds` ends, with the job as it stands; it is `200` when the job failed too, with the failure inside. `Retry-After` and `retry_after_seconds` come on every answer that is not final. Once `contents_id` is… - [Cancel job](https://docs.getclean.ai/api-reference/cancel-job.md): Ask a job to stop, free. The answer is `200` with the job as it stands; the work may finish before it stops, and `Retry-After` comes while it still runs, as on `get_job`. A job already final is unchanged. With pages already parsed the record is `partial`, `canceled`, the pages kept and billed; with… - [List jobs](https://docs.getclean.ai/api-reference/list-jobs.md): List the account's jobs, newest first, free. `state` and `kind` filter them, and every filter you send must match. A job started while you page may make an item repeat; when you merge pages, keep one entry per `id`. - [Fetch contents batch](https://docs.getclean.ai/api-reference/fetch-contents-batch.md): Fetch 1 to 20 pages or documents at their URLs in one call. You get one record per address, kept as a single fetch's is, with a tally first and the sum of the costs last. - [Get contents](https://docs.getclean.ai/api-reference/get-contents.md): Read a record you already have, free: the same copy in any format, at any size, under either view, with the model work the fetch made. - [Get section](https://docs.getclean.ai/api-reference/get-section.md): Read one section of a record, free: its text when it fits, its own text and the rows of its child sections when it does not, and a page of its text when a cut is needed. - [List blocks](https://docs.getclean.ai/api-reference/list-blocks.md): List the blocks of a record, free: by kind, by section, by document page or by id, in document order, one page of results at a time. - [List links](https://docs.getclean.ai/api-reference/list-links.md): List the links of a record, free: every link with its kind and the block and section that hold it, in document order, one page of results at a time, without the 1,000-link cap a fetch puts on `formats: links`. - [List contents](https://docs.getclean.ai/api-reference/list-contents.md): List the records the account keeps, newest first, free. Each item is a `ContentsCompact`: the record's id, outcome, source and dates, with no text, no map, no model work and no cost, and its `execution` as stored. - [Delete contents](https://docs.getclean.ai/api-reference/delete-contents.md): Erase a record before it expires: the record, its screenshot, its raw HTML, its document images, its recognized page images and its stored replays. - [Highlight contents](https://docs.getclean.ai/api-reference/highlight-contents.md): Find words or questions in a record you already have and mark where they stand, without fetching again. You get each place with its section and block ids, and, when you ask for text, the sections that hold them, marked. A string found verbatim is free; one a model has to judge costs one model step,… - [Fill schema](https://docs.getclean.ai/api-reference/fill-schema.md): Fill your JSON Schema from a record you already have. You get a value only where the record states it, never a plausible one, with the place and the cited words for each property, and `empty`, `absent` or `unread` where the record says nothing. It is the same step as `fetch_contents`'s `json_schema`… - [Summarize contents](https://docs.getclean.ai/api-reference/summarize-contents.md): Have a model write a summary of a record you already have, at most 1,500 characters in the content's language, from the copy getclean keeps. It is the same step as `fetch_contents`'s `summary`. Use `highlight_contents` to find words and `fill_schema` to fill fields. - [Compare contents](https://docs.getclean.ai/api-reference/compare-contents.md): Compare a record you already have with a baseline, block by block and cell by cell, without a model, free. - [Search](https://docs.getclean.ai/api-reference/search.md): Search up to ten datasources with one question, in up to twenty wordings, and get one ranked list of results with the facts of each and a receipt of what ran where, before any page is read. - [Get search](https://docs.getclean.ai/api-reference/get-search.md): Read a search you already have, free: the first page as it was answered, and behind it the full list the search stored, including the results it dropped and why. Nothing is searched again and nothing is charged; only the record's `expires_at` moves. - [Search batch](https://docs.getclean.ai/api-reference/search-batch.md): Run 1 to 20 searches in one call, one record each. You get the tally first, then one result per item in input order, each a search record or the problem that skipped it; nothing is atomic, so a skipped item leaves the others standing. Each item carries its own question, wordings, identifiers, countr… - [List datasources](https://docs.getclean.ai/api-reference/list-datasources.md): List the places getclean can search, free; the answer may be cached for an hour. - [Get datasource](https://docs.getclean.ai/api-reference/get-datasource.md): Read one entry of the catalog whole, free; the answer may be cached for an hour. You get what the source covers, how it is reached, which filters and operators it honors, which identifier schemes it resolves and with which issuer codes, and whether it keeps history for `as_of_date`. - [Get limits](https://docs.getclean.ai/api-reference/get-limits.md): Read your key's limits and your account's money in one answer, free, before a batch or any call that must fit a budget. - [The getclean SDKs](https://docs.getclean.ai/sdks/overview.md): Five SDKs generated from the same contract, so every operation is a method with the API's own name and the API's own fields. This page says what every SDK does for you, how to install each one, and where the Python and TypeScript guides go from here. - [getclean for Python](https://docs.getclean.ai/sdks/python.md): The getclean package for Python, for a research agent and for the person who builds one: create the client, make the first fetch and read the record, run the research loop, read a record again for free, upload documents, handle errors, retry safely, and keep every request inside a budget. - [getclean for TypeScript](https://docs.getclean.ai/sdks/typescript.md): The getclean package for TypeScript and JavaScript, for a research agent and for the person who builds one: create the client, make the first fetch and read the record, run the research loop, read a record again for free, upload documents, handle errors, retry safely, and keep every request inside a… ## OpenAPI Specs - [openapi](/openapi.yaml) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.