Short answers to common questions about Fetch, agents, Highlights, billing, tiers, and the docs themselves, each with a link to the page that has the detail.
Short answers to common questions. Each one links to the page that has the detail.
Fetch is Expand's core product. You send a URL and get the page back as Markdown text or a JSON object, with the State JSON behind it and a Snapshot every line links back to. Start with the Fetch overview.
No. They are ways to call Fetch. Use the CLI from a terminal, the TypeScript SDK or the API from application code, MCP from an agent, and hooks or the Skill to route an agent's own web tool through Expand. See Quickstart: Ways to use Expand.
| Need | Use |
|---|---|
| Try one URL from your terminal | Quickstart with the CLI |
| Add Fetch to an app | TypeScript SDK or the API reference |
| Give a coding agent web context | Connect your agent (MCP) |
| Check what a Fetch returned, visually |
Use the CLI to inspect a page locally, in scripts, and in an agent's shell. Use the TypeScript SDK or the API when Fetch is part of your application code. See CLI: Commands and TypeScript SDK.
/v1/fetch return Markdown text?/v1/fetch is Markdown Mode, for the common case where the page goes straight into a prompt. Use /v1/fetch/json, JSON Mode, when your code reads the fields separately, such as the Snapshot ID or the State JSON. See Fetching a URL.
Use JSON Mode when application code needs the Main Markdown, the State JSON, the Snapshot ID, or Fetch Highlights as separate fields of one JSON object. See Fetching a URL and TypeScript SDK.
The Main Markdown is the page's content as Markdown, with navigation, footers, and ads taken out. The State JSON is the data behind the page, such as the JSON its own APIs returned. See How Fetch works.
The State JSON is on by default in both modes. An empty ?include= turns it off. An entry too large to send comes back without body, with moreTokens and a sample of its keys instead, so you can ask for it when you need it. See Fetching a URL.
Fetch returns the Main Markdown first and keeps a pointer to everything it held back, such as the Appendix and large State JSON entries, so your agent reads more only when the task needs it. See Progressive disclosure.
moreTokens missing data?No. They are pointers to content Fetch held back to keep the response small. The Appendix, the replay, and the rest of a large State JSON entry are each one request away. See References to more.
No. Start with the defaults. Add the Appendix, a screenshot, or other extras only when the task needs them. See Include options.
No. Batched Fetch returns the Main Markdown and the State JSON, and does not return screenshots, the Appendix, Highlights, or converted files. See Supported options.
Highlights returns the snippets of a page that answer a question, ranked by relevance, so your agent reads the passages it needs instead of the whole page. See Two ways to highlight.
Not when you highlight a Snapshot you already have. Snapshot Highlights takes the meta.snapshotId from an earlier Fetch and costs 1 credit. Fetch Highlights runs as part of a new Fetch. See Two ways to highlight.
Yes. By default Highlights searches the Main Markdown and the State JSON. The Appendix is searched only when you include it. See Two ways to highlight.
Every snippet carries a location with an evidence ID. From MCP, each snippet also carries a citationUrl. From the API or the TypeScript SDK, build the link with the SDK's citation helpers. See Working with snippets and TypeScript SDK.
Yes, when the page is safe to share. Snapshot links are public, so anyone with a link can open it. Do not fetch private pages, secrets, or customer data you do not want shared. See Who can read a Snapshot.
A hook routes an agent's built-in web-fetch tool through Expand. The Skill teaches the agent how to use Expand from its shell. MCP gives the agent Fetch as a native tool. See CLI: Skill & hooks.
OpenCode. Claude Code, Cursor, Codex, and fx get the Skill and the MCP server instead. See CLI: Commands.
It can be, when the agent can read the Skill and run terminal commands. Add MCP when you want native tool calls, or when the agent should not depend on a shell. See CLI: Skill & hooks.
expandai login or EXPAND_API_KEY?For an agent on your machine, run expandai login once. The CLI and the local MCP server read that sign-in. Use EXPAND_API_KEY for the TypeScript SDK, the API, servers, and CI. See Connect your agent (MCP) and Authentication.
/start.md?/start.md is the setup guide for agents, as one Markdown document. Give it to an agent and the agent picks the right setup for itself. See start.md.
Most often the install ran in a different directory, the agent needs a restart, or the MCP configuration landed in a different scope than the agent is using. See Troubleshooting.
No. Expand bills in prepaid credits per delivered output, not per token. See Pricing & Usage.
1 credit, and 1,000 credits cost $1. Highlights adds 1 credit, each converted document page adds 1, each vision-model page adds 5, a video adds 5, and transcribed audio adds 10 a minute. See Credit costs.
No. You pay for delivered content, not for attempts. The one surprise is that an origin's 404 or 500 page is a real capture, so it costs 1 credit like any other page. Check originError before you treat the content as the page you asked for. See What you are charged for, by outcome.
Check the status and the error body together. A browser page Fetch can return 200 with an originError when the origin served an error page, or a FetchOriginError when it could not be reached. A file Fetch can instead return 404, 410, or 502 with FetchOriginHttpError when the origin refuses the file. Other non-2xx responses describe API or capture errors. See When the origin fails.
Credits are Expand's prepaid unit. You buy them at $1 per 1,000, and delivered work draws them down. A Fetch costs 1 credit. Your first organization starts with 10,000 welcome credits. See Credits and balance.
Purchased credits stay on your balance until you spend them. Welcome credits expire 365 days after they are granted. See Credits and balance.
Expand checks your balance before it admits a request, so a request with no credits behind it is refused rather than run and billed. Buy credits in Billing and the block clears immediately. See Access when credits run out.
No. Tiers raise the browser concurrency included with your account as you spend credits and time passes. They do not change what anything costs. See Concurrency tiers.
Tiers 2 to 5 need both a spend threshold and a number of days since your first transaction. If the spend is there and the days are not, the next tier is not active yet. See Why am I not in the next tier?.
The number of browser captures your organization can run at once. At the limit, a single Fetch is refused with 429 FetchConcurrencyLimitExceeded and Batched Fetch queues instead. See Limits.
No. Provisioned browsers add to your total browser concurrency and leave your tier as it is. See Provisioned browsers.
Adding browsers takes effect immediately. Removing browsers takes effect at the end of the month you paid for. See Provisioned browser concurrency.
The docs explain what each product does and how to use it. The API reference holds the exact request and response schemas, errors, and generated examples. Open the API reference.
In the API reference. The docs link to it instead of repeating every schema.
Yes. Every docs and API reference page is available as Markdown, and start.md, llms.txt, and llms-full.txt give an agent a compact way in. See Any page as Markdown.
/start.md, llms.txt, and llms-full.txt?/start.md is the setup guide for agents. llms.txt is a compact index of the docs. llms-full.txt is the whole docs bundle, for agents that need more context. See start.md, llms.txt, and llms-full.txt.
Yes. Append .md to the page's path, or request the page with Accept: text/markdown. See Any page as Markdown.
| Playground & replay |