Skip to main content
Glama

List, search or read a run's pages

list_pages
Read-onlyIdempotent

List the pages a project run stored; with q, find the pages whose text or markup matches; with url, read one page in full, with its versions across runs. Use it for what a project's runs stored: what a run covered, which pages say something, one page's text. search_web searches the live web instead, get_job reads a crawl_site crawl, scrape_urls fetches a live copy, and get_changes lists only what changed. Inputs: project_id from list_projects. q='free trial' needs both words, q='"free trial"' the phrase; mode='selector' takes CSS such as 'form#signup' and needs a run that kept html (the rawHtml format). url is an address, not a search term: scheme and trailing slash may differ, the rest must match, query string included. Give q or url, not both. run_id from list_runs picks the run. Limits: a listing has up to 500 rows, shallowest first, so use q to reach pages past them. A page read in full has each body capped at 12,000 characters, and a URL the runs did not store answers 404. Read-only and free: it reads stored data and never fetches.

Input Schema

NameRequiredDescriptionDefault
qNoText to find, 1 to 200 characters: words or a "quoted phrase", or with mode='selector' a CSS selector or an XPath starting with / or (. Omit to list every page.
urlNoOne page's full URL, as a listing shows it, to read that page in full; omit to list.
modeNoWith q: 'content' (default) searches the markdown, 'selector' the stored html.content
run_idNoA run's id, from list_runs; empty means the latest finished run, or with url the newest copy across the project's last 50 runs.
project_idYesThe project's 32-character hex id, from list_projects.

Output Schema

NameRequiredDescriptionDefault
urlNoWith url: the page's URL as stored.
codeNoOnly on a failure: a machine-readable reason, e.g. read_only, validation, plan_limit or not_found.
headNoWith url: {title, description, canonical, h1, ...}.
hitsNoWith q: up to 500 matches, each {url, count (matches on the page), snippet}.
htmlNoWith url: the raw html, when the run kept it.
textNoWith url: plain text, when kept.
errorNoOnly when the call failed: what went wrong, in words an assistant can act on.
pagesNoListing: up to 500 rows, shallowest first, each {url, path, status, depth, words, changed, title, crawledAt}.
runIdNoThe run these pages are from (with url, the run this copy is from); null when the project has no finished run.
wordsNoWith url: words in its markdown.
detailNoOnly on a failure: the API's own wording, when the error was rephrased.
fieldsNoWith url: fields the project's json_schema extracted, or null.
noBodyNoWith q: pages skipped because the body the mode needs was not kept (rawHtml for selector).
statusNoWith url: the HTTP status the site answered. On an error, the API's status code.
scannedNoWith q: pages searched.
markdownNoWith url: its main content as markdown, capped at 12,000 characters.
versionsNoWith url: every stored copy across runs, newest first, each {runId, crawledAt, contentHash, words, status}; a changed contentHash is a changed page.
cleanHtmlNoWith url: simplified html, when kept.
crawledAtNoWith url: when this copy was read (ISO 8601).
linkGraphNoListing: the run's link-graph summary (orphans, unlisted pages, dead ends), or null.
truncatedNoWith q: true when more pages matched than are listed.
pageStatusNoWith url: ok, blocked, captcha, missing (404/410), timeout, redirect, robots or skipped.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed18 schema fields changed
    • changedInput schema / properties / run_id / description
      Previous value: -"A run's id, from list_runs; empty means the project's latest finished run."New value: +"A run's id, from list_runs; empty means the latest finished run, or with url the newest copy across the project's last 50 runs."
    • addedInput schema / properties / url
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "One page's full URL, as a listing shows it, to read that page in full; omit to list.",
      +  "title": "Url"
      +}
    • changedOutput schema / description
      Previous value: -"A run's pages, or with q the pages that match."New value: +"A run's pages; with q the pages that match; with url one page in full."
    • addedOutput schema / properties / cleanHtml
      Added value: +{
      +  "description": "With url: simplified html, when kept.",
      +  "title": "Cleanhtml"
      +}
    • addedOutput schema / properties / crawledAt
      Added value: +{
      +  "description": "With url: when this copy was read (ISO 8601).",
      +  "title": "Crawledat"
      +}
    • addedOutput schema / properties / fields
      Added value: +{
      +  "description": "With url: fields the project's json_schema extracted, or null.",
      +  "title": "Fields"
      +}
    • addedOutput schema / properties / head
      Added value: +{
      +  "description": "With url: {title, description, canonical, h1, ...}.",
      +  "title": "Head"
      +}
    • addedOutput schema / properties / html
      Added value: +{
      +  "description": "With url: the raw html, when the run kept it.",
      +  "title": "Html"
      +}
    • changedOutput schema / properties / linkGraph / description
      Previous value: -"Without q: the run's link-graph summary (orphans, unlisted pages, dead ends), or null."New value: +"Listing: the run's link-graph summary (orphans, unlisted pages, dead ends), or null."
    • addedOutput schema / properties / markdown
      Added value: +{
      +  "description": "With url: its main content as markdown, capped at 12,000 characters.",
      +  "title": "Markdown"
      +}
    • addedOutput schema / properties / pageStatus
      Added value: +{
      +  "description": "With url: ok, blocked, captcha, missing (404/410), timeout, redirect, robots or skipped.",
      +  "title": "Pagestatus"
      +}
    • changedOutput schema / properties / pages / description
      Previous value: -"Without q: up to 500 rows, shallowest first, each {url, path, status, depth, words, changed, title, crawledAt}."New value: +"Listing: up to 500 rows, shallowest first, each {url, path, status, depth, words, changed, title, crawledAt}."
    • changedOutput schema / properties / runId / description
      Previous value: -"The run these pages are from; null when the project has no finished run."New value: +"The run these pages are from (with url, the run this copy is from); null when the project has no finished run."
    • changedOutput schema / properties / status / description
      Previous value: -"Only on a failure: the HTTP status code."New value: +"With url: the HTTP status the site answered. On an error, the API's status code."
    • addedOutput schema / properties / text
      Added value: +{
      +  "description": "With url: plain text, when kept.",
      +  "title": "Text"
      +}
    • addedOutput schema / properties / url
      Added value: +{
      +  "description": "With url: the page's URL as stored.",
      +  "title": "Url"
      +}
    • addedOutput schema / properties / versions
      Added value: +{
      +  "description": "With url: every stored copy across runs, newest first, each {runId, crawledAt, contentHash, words, status}; a changed contentHash is a changed page.",
      +  "title": "Versions"
      +}
    • addedOutput schema / properties / words
      Added value: +{
      +  "description": "With url: words in its markdown.",
      +  "title": "Words"
      +}
  2. Changed5 schema fields changed
    • addedInput schema / properties / mode
      Added value: +{
      +  "default": "content",
      +  "description": "With q: 'content' (default) searches the markdown, 'selector' the stored html.",
      +  "enum": [
      +    "content",
      +    "selector"
      +  ],
      +  "title": "Mode",
      +  "type": "string"
      +}
    • changedInput schema / properties / project_id / description
      Previous value: -"The project's id, as list_projects or create_project returns it."New value: +"The project's 32-character hex id, from list_projects."
    • addedInput schema / properties / q
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Text to find, 1 to 200 characters: words or a \"quoted phrase\", or with mode='selector' a CSS selector or an XPath starting with / or (. Omit to list every page.",
      +  "title": "Q"
      +}
    • changedInput schema / properties / run_id / description
      Previous value: -"A run's id, from list_runs, start_run or the runId a list_pages answer carries; leave empty for the last finished run."New value: +"A run's id, from list_runs; empty means the project's latest finished run."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": true,
      +  "description": "A run's pages, or with q the pages that match.",
      +  "properties": {
      +    "code": {
      +      "description": "Only on a failure: a machine-readable reason, e.g. read_only, validation, plan_limit or not_found.",
      +      "title": "Code"
      +    },
      +    "detail": {
      +      "description": "Only on a failure: the API's own wording, when the error was rephrased.",
      +      "title": "Detail"
      +    },
      +    "error": {
      +      "description": "Only when the call failed: what went wrong, in words an assistant can act on.",
      +      "title": "Error"
      +    },
      +    "hits": {
      +      "description": "With q: up to 500 matches, each {url, count (matches on the page), snippet}.",
      +      "title": "Hits"
      +    },
      +    "linkGraph": {
      +      "description": "Without q: the run's link-graph summary (orphans, unlisted pages, dead ends), or null.",
      +      "title": "Linkgraph"
      +    },
      +    "noBody": {
      +      "description": "With q: pages skipped because the body the mode needs was not kept (rawHtml for selector).",
      +      "title": "Nobody"
      +    },
      +    "pages": {
      +      "description": "Without q: up to 500 rows, shallowest first, each {url, path, status, depth, words, changed, title, crawledAt}.",
      +      "title": "Pages"
      +    },
      +    "runId": {
      +      "description": "The run these pages are from; null when the project has no finished run.",
      +      "title": "Runid"
      +    },
      +    "scanned": {
      +      "description": "With q: pages searched.",
      +      "title": "Scanned"
      +    },
      +    "status": {
      +      "description": "Only on a failure: the HTTP status code.",
      +      "title": "Status"
      +    },
      +    "truncated": {
      +      "description": "With q: true when more pages matched than are listed.",
      +      "title": "Truncated"
      +    }
      +  },
      +  "title": "PagesOut",
      +  "type": "object"
      +}
  3. Changed1 schema field changed
    • changedInput schema / properties / run_id / description
      Previous value: -"A run's id, from start_run or the runId a list_pages answer carries; leave empty for the last finished run."New value: +"A run's id, from list_runs, start_run or the runId a list_pages answer carries; leave empty for the last finished run."
  4. Changed2 schema fields changed
    • addedInput schema / properties / project_id / description
      Added value: +"The project's id, as list_projects or create_project returns it."
    • addedInput schema / properties / run_id / description
      Added value: +"A run's id, from start_run or the runId a list_pages answer carries; leave empty for the last finished run."
  5. First observed

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, non-destructive, closed-world, but the description adds genuinely new behavioral facts: 500-row listing limit with shallowest-first order, 12,000-character body cap per page, 404 for un-stored URLs, and the 50-run window for url reads. This is context annotations cannot provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then cleanly partitioned into 'Inputs' and 'Limits' groupings. Despite the density, every sentence carries operational information (syntax, defaults, limits) with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-param tool with an output schema and rich annotations, nothing an agent needs to call it correctly is missing: routing against five siblings, query/URL syntax, run defaults, pagination limits, and body caps are all covered.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (baseline 3), but the description adds meaning beyond it: boolean-vs-phrase query syntax ('free trial' vs '"free trial"'), selector CSS example, URL matching rules (scheme/trailing slash tolerance, query string must match), and run_id defaulting behavior for the two modes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource and enumerates all three modes: list stored pages, search by q, read one page by url. It explicitly differentiates from siblings (search_web, get_job, scrape_urls, get_changes), so an agent can select it without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names each alternative and the condition that selects it ('search_web searches the live web instead, get_job reads a crawl_site crawl...'). It also states an explicit exclusion ('Give q or url, not both') and when a run is needed for selector mode.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.