Read any page or file.
Stay in control.

1. Create an account

Sign in through the app, or create an agent without a browser. Save the returned secret once; it is never shown again.

POST https://scrape.agnt.gg/scrape/v1/agents
Content-Type: application/json

{"name":"research-agent","allowPrepaid":true}

2. Fund and authorize usage

Use the returned funding link or x402. Human owners enable extra usage and set account budgets in the app. Initial agent credentials carry execution, receipts and funding scopes with a $10 monthly key cap; an explicit request spending cap is also required.

3. Scrape a page

POST /scrape/v1/scrape
Authorization: Bearer YOUR_SCRAPE_KEY
Idempotency-Key: unique-request-20260924-001
Content-Type: application/json

{"url":"https://example.com/article","formats":{"markdown":true,"links":true},"maxChargeMicroUSD":4000}

Returns success, url, finalUrl, statusCode, title and formats. Each requested format is an object with requested, success and data, so one failed format never costs you the others; isPartial is true when that happens. Omit formats for markdown only.

Formats

• markdown · headings, lists, emphasis, tables, absolute links, and fenced code with its language.
• html · the cleaned main-content element, or the full rendered page with mainContentOnly false.
• text · readable text with whitespace collapsed.
• links · every absolute http(s) link on the whole page, de-duplicated.
• code · every <pre> block from the whole page as fenced code.
• screenshot · a JPEG of the 1366×900 viewport, as a data URL. Web pages only.
• bytes · the original response body, as the server sent it, as a data URL (up to 4 MiB).

mainContentOnly (default true) removes navigation, headers, footers, sidebars, cookie banners and ads before markdown, html and text are built. waitForMs (0–10,000) adds time after the page settles, for content that loads late.

Files & documents

When a URL serves a file instead of a web page, Scrape converts it instead of rendering it, and the response gains a document object (type, size, and pages, sheets, slides or items). The same formats apply, and one file costs one page. The type is read from the file's signature first, then its content type, then its extension, so a mislabelled download still converts correctly.

• PDF · markdown with a section per page, links from the text and from link annotations, and the document title. pageRange selects pages ("5" or "2-9"), up to 500 per request. A scanned PDF with no text layer returns 422 pdf_images_only, free; text recognition is not offered.
• Word (docx) · headings, bold and italics, lists, links and tables.
• Excel (xlsx, xlsm) · one markdown table per sheet, headed by the sheet name; up to 2,000 rows and 100 columns per sheet.
• PowerPoint (pptx) · one section per slide in presentation order, with its title, text, tables and speaker notes.
• CSV and TSV · a markdown table, quoted fields handled.
• RSS and Atom feeds · each item as a linked heading with its date and a plain-text summary.
• JSON, YAML, XML and SVG · fenced blocks; JSON is pretty-printed.
• Source code · a fenced block tagged with its language.
• Markdown, text, logs, RTF and HTML files · as readable text.
• Images (png, jpg, gif, webp, bmp) · format, dimensions and size. Images are not described or read.

Supported extensions: pdf, docx, xlsx, xlsm, pptx, csv, tsv, json, geojson, yaml, yml, xml, rss, atom, svg, html, htm, xhtml, md, markdown, mdx, txt, text, log, rtf, png, jpg, jpeg, gif, webp, bmp, js, mjs, cjs, jsx, ts, tsx, py, rb, go, rs, java, kt, c, h, cpp, cc, hpp, cs, php, swift, sh, bash, zsh, ps1, sql, css, scss, less, toml, ini, cfg, conf, lua, r, dart, scala, pl, ex, exs, vue, svelte, graphql, proto, tf, jsonl. Legacy binary Office files (doc, xls, ppt) return 415 unsupported_file_type. Files are limited to 20 MiB.

Upload a file

For a file you already hold, send its bytes as the request body. No multipart, no JSON wrapper; options go in the query string.

curl -X POST "https://scrape.agnt.gg/scrape/v1/parse?extension=pdf&formats=markdown,links&pageRange=1-10" \
  -H "Authorization: Bearer YOUR_SCRAPE_KEY" \
  -H "Idempotency-Key: parse-report-001" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

The response has the same shape as a scrape, including document. Formats are markdown, html, text, links and code. The same Idempotency-Key with the same file returns the receipt; with a different file it is a 409 conflict. Uploads are billed exactly like pages and are never stored.

Blocked pages

Some sites refuse automated access. When the page we receive is a challenge, a captcha or a refusal, you get 422 page_blocked instead of that page, and no charge. A page that does not exist returns 404 page_not_found, also free. We never solve captchas, sign in on your behalf, or reach private or internal addresses. For sites that refuse all automated access, fetch the page from your own browser.

Payments

Stripe Checkout funds $10, $25 or $50 prepaid credit. Credit appears only after verified payment. Requests debit prepaid credit only when explicitly authorized. No unlimited allowance.

Monthly plans

Optional and standalone — no AGNT subscription required. POST /hosting/purchase with an Idempotency-Key and a tier of starter, pro or business. The price is debited from prepaid credit, so there is never an automatic card charge. Starter $5 includes 2,250 pages; Pro $15 includes 7,000; Business $39 includes 18,000. Buying a higher tier mid-month upgrades in place and charges only the difference; moving down happens at renewal. Plans renew only when you enable renewal, and allowances never roll over.

x402 / USDC on Base

1. POST /funding/x402 with amountCents and Idempotency-Key using a funding-scoped key.
2. Read HTTP 402 and the base64 PAYMENT-REQUIRED header.
3. Authorize exactly the stated USDC amount, destination, chain and validity in your wallet.
4. POST /funding/x402/:orderId with PAYMENT-SIGNATURE.
5. Read PAYMENT-RESPONSE and the credited receipt. If pending, poll that order; never pay a second order to recover a timeout.

Scrape does not hold wallet signing keys. Funding does not authorize unlimited usage.

Limits & retries

• One page costs $0.004, whatever formats you request. A page draws on your included allowance first.
• maxChargeMicroUSD: 0 means included-only. Cash also requires account authorization and available account/key budgets.
• 30 attempted pages per account per minute. Each page has a 45-second limit; configure clients for at least 60 seconds. Pages queue briefly when every browser is busy; a full queue returns 429 service_busy.
• 6 MiB returned JSON, a 10 MiB web page and a 20 MiB file. Excessive content fails, not silently truncates.
• Blocked and failed pages release their reservation, but attempt limits still apply: sixty failed pages in an hour pauses further requests. Reuse the same idempotency key for uncertain retries, never a fresh key.
• We store receipts, not page content. A retry returns the receipt and resultRetained:false, without visiting the page again. Save the original result on your side.

Errors

400 invalid input · 401 invalid credentials · 402 funding/spending limit · 403 insufficient scope or a non-public destination · 404 page_not_found · 409 conflicting or running request · 413 result_too_large · 415 unsupported_file_type · 422 page_blocked, extraction_failed or pdf_images_only · 429 rate/capacity limit · 502 the site did not answer · 503 unavailable · 504 scrape_timeout. Check the stable error code and request receipt before retrying.

Keys

scrape:execute, scrape:read and scrape:fund are independent. Keys last until you revoke them; set an optional expiresAt when creating one if you want a short-lived key. Email sign-in is required to create keys or change spending controls. An AGNT sign-in token is also accepted as a bearer. Never put API secrets in browser pages you publish.

Signed notifications

Register up to three public HTTPS receivers in the app or POST /webhooks. Save the one-time signing secret. Verify X-AGNT-Signature as v1=HMAC-SHA256(secret, timestamp + "." + rawBody), using X-AGNT-Timestamp with a five-minute tolerance. Deduplicate X-AGNT-Event-ID. Delivery is at least once with up to three attempts; history is retained seven days. Notifications contain receipts and state, never page content.

Privacy & acceptable use

Every page is rendered in a single-use browser inside an isolated virtual machine that can reach only public internet addresses. The browser is destroyed after each page. AGNT retains account, payment and request metadata for operation and accounting, but does not store page content or the URLs you scrape. Avoid putting secrets in URLs. Scrape only content you are permitted to access; no authentication bypass, abusive crawling or access to private infrastructure.

Monthly plans are optional and are paid from prepaid credit. Plan and AGNT bundle allowances reset each period; no rollover. Financial records are retained for accounting. Contact support@agnt.gg for account, billing or data requests.

Client downloads

Save each response when it arrives. Use the same idempotency key for an uncertain retry; receipts do not include previously returned content.