> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Describe a crawl

> Turn a plain-language request such as only the blog posts into crawl options without starting a crawl or reading any page. Check the options, then send them.

`POST /v1/crawl/params-preview` turns a sentence into crawl options. Use it when you do not know which path patterns or depth to set. No pages are read. Needs an API key.

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/crawl/params-preview \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://bun.com",
    "prompt": "only the blog posts, two links deep"
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "url": "https://bun.com/",
    "includePaths": ["blog/.*"],
    "maxDiscoveryDepth": 2
  },
  "costUsd": 0.003
}
```

`url` and `prompt` (1 to 1,000 characters) are required. `data` holds only the fields it set, from `url`, `includePaths`, `excludePaths`, `maxDiscoveryDepth`, `crawlEntireDomain`, `allowSubdomains`, `allowExternalLinks`, `sitemap`, `ignoreQueryParameters` and `limit`, described in [Crawl](https://docs.stophy.dev/crawl/overview#scope). It never sets `scrapeOptions`.

The options are a suggestion, so read them, then send them to `POST /v1/crawl`. Patterns that are not valid regular expressions are dropped, and at most 20 of each are returned. `maxDiscoveryDepth` is at most 10. A request with nothing to set returns only `url`. See [Pricing](https://docs.stophy.dev/account/pricing.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.