# Read API · Onto > Turn any URL into clean Markdown and an AIO score in one call. Free for 1,000 credits a month, no card. **Source:** /read-api **Extracted:** 2026-09-24T18:14:20.135Z --- Product · Read API ## Read any URL. Get agent-ready content. One POST returns any page as clean Markdown — clutter gone, JSON-LD kept — with a 0–100 AIO score when you want one. 1 credit a read, and failed reads are refunded. [Get an API key →](https://app.buildonto.dev/signup)[Try it here](#try) [Read the docs ↗](https://docs.buildonto.dev/api/read) 699 → 17 KB stripe.com/pricing, measured 1 credit a read · failures refunded 6 endpoints · also over MCP Try it ### Run it on any page. The Score tab runs Onto's free scan right here — the score, the faults and the Markdown an agent is handed. The other tabs open your dashboard playground with the URL filled in. ReadBatchScorefreeRead & scoreMapExtract https://free scan Show:MarkdownJSON Get codeScanfree Trystripe.com/pricingvercel.com/pricinglinear.app/pricing Measured ### What one read saves. Real pages, not a guess. 5 live pricing pages, each fetched once on 23 Sep 2026 and cleaned by the same engine the API runs. HTML, as served Markdown, as Onto serves itMeasured 23 Sep 2026 · one GET of each live page · cleaned by the engine the API runs HTML against Markdown, measured 23 Sep 2026 | Page | HTML | Markdown | Lighter | | --- | --- | --- | --- | | stripe.com/pricing | 699 KB | 17 KB | 97.6% | | vercel.com/pricing | 1,199 KB | 15.4 KB | 98.7% | | linear.app/pricing | 801 KB | 3.4 KB | 99.6% | | notion.com/pricing | 501 KB | 23.2 KB | 95.4% | | github.com/pricing | 688 KB | 34.7 KB | 95% | How a read runs ### From your POST to the Markdown. Nine steps between the request and the answer. Watch them, or click a step. api.buildonto.dev POST /v1/read { url } 1. 01Check the key Looked up by its hash — Onto never keeps the key itself. 2. 02Take a credit From your month's credits. A failed read is refunded. 3. 03Look in the cache Kept for an hour. `"fresh": true` skips it. * `hit`→answer from the cache * `miss`→carry on 4. 04Check the address Public hosts only, checked again on every redirect. 5. 05Read robots.txt If it shuts out GPTBot or every crawler, Onto stops before fetching. 6. 06Fetch the page 15 seconds, up to 5 redirects, 10 MB at most, no JavaScript run. 7. 07Clean it Through `@ontosdk/core` — the same cleaner the Serve SDK runs at build. 8. 08Score it An AIO score, returned by `/v1/score` and `/v1/read-and-score`. 9. 09Answer Cached, logged, and sent back. JSON — or raw Markdown with Accept: text/markdown What it reads ### Pages, PDFs and whole sites. What you can send, what comes back, and what it costs. You sendYou get backRoute · cost 1. **A web page** Clean Markdown. Navigation, scripts, ads and footers go; headings, lists, tables and links stay, and the page's JSON-LD is kept as a Structured Data block. `/v1/read`_1 credit_ 2. **A PDF** Its text, up to 20 pages. PDFs aren't scored. An image-only PDF has no text to return, so the read fails with IMAGE\_PDF and the credit comes back. `/v1/read`_1 credit_ 3. **JSON, CSV or plain text** Passed straight through — nothing to clean. `/v1/read`_1 credit_ 4. **A page's facts** The JSON-LD, OpenGraph and meta tags the page declares, as data. Pattern matching only — no model decides anything. `/v1/extract`_1 credit_ 5. **A whole site** Its URLs — from the sitemap, or the first page's links if there isn't one. Up to 1,000. `/v1/map`_1 credit_ 6. **Many pages at once** Up to 50 URLs read, scored or extracted in one call. Every URL that fails is refunded. `/v1/batch`_1 per URL_ Scoring ### AIO score, 0–100. Starts at 100 and subtracts for named faults, so every lost point is one you can fix. Each score comes with one hallucination-risk rating for the page — low, medium or high — so your agent knows when to double-check. acme.com _example_ **65**/ 100 Needs workmedium hallucination risk Starts at 100 and subtracts. 3 faults, 35 points — every one traceable to a named check, no weighting to audit. 1. robots.txt lets AI crawlers inGPTBot and \* allowed0 2. A Markdown version existsfound — a page without one loses 250 3. Served through the Onto SDKMarkdown found, but not served by the SDK−10 4. Code-to-content noisenot scored — a Markdown version exists— 5. Page under 200 KBnot scored — a Markdown version exists— 6. JSON-LD schema markupnone found on the page−20 7. Two or more headingsh1 / h2 / h30 8. Every image has alt textone image missing alt−5 The routes ### Six routes, one key. The real request and the fields that come back, with the MCP tool and the credit cost for each. Tokens saved reading stripe.com/pricing 174,618 One read of the live page, cleaned by the same engine as the API · ≈4 bytes per token **699 KB**HTML in **17 KB**Markdown out **97.6%**lighter **23 Sep 2026**measured 01/readClean Markdown + metadata02/read + scoreMarkdown and its score, one call03/scoreAIO score, 0–10004/batchUp to 50 URLs · failures refunded05/mapURL list from sitemap06/extractJSON-LD, OpenGraph, meta /v1/read $ curl api.buildonto.dev/v1/read \\ \-H "Authorization: Bearer onto\_sk\_…" \\ \-d '{"url":"https://stripe.com"}' { "status": "success", "url": "https://stripe.com", "markdown": "# Stripe\\n\\n…", "metadata": { title, description, language }, "stats": { raw\_html\_size\_kb, markdown\_size\_kb, reduction\_percent }, } _MCP_read\_url_Cost_1 credit Pricing ### Pay for credits, not seats. Every tier has every endpoint, the score and the MCP server — tiers buy credits and concurrency. Paid tiers can top up with credit packs. 2 concurrent · hard monthly cap $0forever 1,000 credits / month [Start free](https://app.buildonto.dev/signup) Includes * Read · Score · MCP server * Clean Markdown + AIO accuracy score * Community support 5 concurrent · top up with credits $9/ month 10,000 credits / month [Upgrade to Starter](https://app.buildonto.dev/read/billing) Includes * Everything in Free * Credit packs unlock overage * Email support 20 concurrent · top up with credits $49/ month 100,000 credits / month [Upgrade to Growth](https://app.buildonto.dev/read/billing) Includes * Everything in Starter * 10× Starter's monthly credits * Credit packs unlock overage 50 concurrent · shared Slack $250/ month 500,000 credits / month [Upgrade to Scale](https://app.buildonto.dev/read/billing) Includes * Everything in Growth * Shared Slack support * 50 reads in flight at once Questions ### Things developers ask before signing up. 01How is this different from running my own scraper? A scraper hands you HTML. The Read API hands you the page as Markdown an LLM can use directly — clutter stripped, JSON-LD kept — and can score it, so you know whether it's worth feeding to your model. It also handles the unglamorous parts: robots.txt, redirects, PDFs, and refusing private addresses. 02How is the AIO score worked out? It starts at 100 and subtracts for named faults — no JSON-LD, fewer than two headings, images without alt text, and so on. Every response lists the penalties it applied, so you can see exactly why a page scored what it did. /v1/score is free; /v1/read-and-score returns the score with the Markdown for 1 credit. 03Can I read PDFs? Yes, with /v1/read: you get the text of up to 20 pages. PDFs aren't scored — /v1/score says so, and /v1/read-and-score returns a null score. An image-only PDF has no text to return, so the read fails with IMAGE\_PDF and the credit is refunded. 04What happens when my monthly credits run out? On Free, calls return 429 RATE\_LIMITED until the month resets at 00:00 UTC on the 1st — you're never charged. On paid plans, calls draw from your credit balance, which you top up with packs: $5 for 500, $20 for 2,200, $50 for 6,000 or $200 for 28,000. If that's empty too, calls return 402 PAYMENT\_REQUIRED. 05Do cached reads cost credits? Yes. A read is cached for an hour, keyed on the exact URL, so a repeat comes back without fetching the page again — but it's still a read, and still costs its credit. Send `"fresh": true` to skip the cache. 06Is there an official MCP server? Yes. Connect by URL — `https://api.buildonto.dev/mcp` — in Claude, ChatGPT, Cursor or Codex, or run `@ontosdk/mcp` locally with npx. Its six tools call the same endpoints and spend the same credits. [More on MCP](/mcp-server). 07Does it respect robots.txt? It reads robots.txt before fetching. If the site disallows everything to GPTBot or to every crawler, the read stops with `ROBOTS_BLOCKED` before the page is touched. Requests identify themselves as Onto-Reader — [about our bot](/about-bot). 08Do you store the pages I read? The result sits in the cache for an hour, then it's gone — and every deploy starts the cache empty. What stays is the URL of each request, in your usage log; that's what the Usage page shows you. Get started ### Start reading the web like an agent. 1,000 credits a month, free. No card, no sales call. [Get an API key →](https://app.buildonto.dev/signup)[See all pricing](/pricing) Free tier · 1,000 credits / month · no card required --- ## Structured Data (JSON-LD) ```json { "@context": "https://schema.org", "@graph": [ { "@type": "Organization", "@id": "https://buildonto.dev/#org", "name": "Onto", "url": "https://buildonto.dev", "logo": "https://buildonto.dev/icon.png", "sameAs": [ "https://x.com/buildonto", "https://github.com/ravixalgorithm/ontosdk" ] }, { "@type": "WebSite", "@id": "https://buildonto.dev/#site", "url": "https://buildonto.dev", "name": "Onto", "publisher": { "@id": "https://buildonto.dev/#org" } }, { "@type": "SoftwareApplication", "name": "Onto", "applicationCategory": "DeveloperApplication", "operatingSystem": "Web", "url": "https://buildonto.dev", "description": "Onto serves AI agents clean Markdown from your own site, at the same URL, and shows you which agents came. Plus the AIO score, a Read API and an MCP server.", "publisher": { "@id": "https://buildonto.dev/#org" }, "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD", "description": "Free tier: 1,000 credits / month" } } ] } ```