# Web map

> List a website’s URLs, optionally ranked or filtered by a topic.

`web_map` lists the URLs of a website, from its sitemap and links, with page titles where they’re known. Use it to find the right page on a site before reading it with [`web_scrape`](https://clonvo.com/docs/web-scrape.md). Set `search` to rank or filter the URLs by a topic.

Call it with `POST /v1/tools/web_map`, or as `web_map` over [MCP](https://clonvo.com/docs/mcp.md).

## Arguments

-   `url` string Required
    
    The site to map: its home page or any page on it.
    
-   `search` string
    
    Only or first the URLs about this, e.g. "pricing" or "API reference".
    
-   `max_results` integer
    
    How many URLs to return (1–1000, default 100).
    
-   `include_subdomains` boolean
    
    Also list URLs on the site’s subdomains (default false).
    

## Example

```bash
curl https://api.clonvo.com/v1/tools/web_map \
  -H "Authorization: Bearer $CLONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "arguments": { "url": "https://www.postgresql.org", "search": "release notes", "max_results": 3 } }'
```

```json
{
  "id": "gen-01M6A1B3C5D7F9H1K3M5P7R9T1",
  "tool": "web_map",
  "provider": "clonvo",
  "result": {
    "url": "https://www.postgresql.org",
    "links": [
      { "url": "https://www.postgresql.org/docs/release/", "title": "PostgreSQL: Release Notes", "description": null },
      { "url": "https://www.postgresql.org/docs/18/release-18.html", "title": "PostgreSQL: Documentation: 18: Release 18", "description": null },
      { "url": "https://www.postgresql.org/docs/17/release-17.html", "title": "PostgreSQL: Documentation: 17: Release 17", "description": null }
    ]
  },
  "usage": { "cost": 0.002, "charged": 0.00204, "is_byok": false }
}
```

## Result

| Field | Description |
| --- | --- |
| `url` | The site you asked to map. |
| `links[]` | The URLs found, most relevant first when you set `search`. |
| `links[].url` | The page’s URL. |
| `links[].title`, `links[].description` | The page’s title and description, when known; otherwise `null`. |
| `notes` | Present when the provider handled an argument differently. |

The fields around `result` (`id`, `tool`, `provider`, `usage`) are the same for every tool; see [Calling tools](https://clonvo.com/docs/calling-tools.md#response).

## Notes

-   Results can differ slightly between providers: some read the sitemap, others follow links from the URL, and titles are present only when the provider returns them. `notes` says when an argument was handled differently.