# Web Scraping API guide



## Start with Web Scraping



Map a public site, retrieve selected pages and extract structured page content. Start with bounded single-page reads before using asynchronous crawls or browser sessions.



These requests use your API key and can spend credits. Check the current price on the endpoint page; each new page is a separate request. Later examples use illustrative identifiers: replace them with values from your earlier response.



### 1. Discover site URLs



Mapping discovers URLs. It does not fetch the content of every discovered page. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/web/map)



**web/map**

```
curl "https://www.monocrawl.com/v1/web/map?url=https%3A%2F%2Fexample.com&limit=10" \
  -H "x-api-key: mn_your_key_here"
```



### 2. Retrieve a selected page



Replace the example URL with a returned public page and choose the output formats your application needs. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/web/scrape)



**web/scrape**

```
curl "https://www.monocrawl.com/v1/web/scrape?url=https%3A%2F%2Fexample.com&formats=markdown%2Cmetadata" \
  -H "x-api-key: mn_your_key_here"
```



### 3. Read structured page content



Use the same selected page if you need the extractor’s fields. This is another request; reuse saved scrape output when it already answers the task. [Parameters and current cost →](https://www.monocrawl.com/docs/endpoints/web/extract)



**web/extract**

```
curl "https://www.monocrawl.com/v1/web/extract?url=https%3A%2F%2Fexample.com" \
  -H "x-api-key: mn_your_key_here"
```



## Choose filters with the source behavior in mind



| Control | Behavior and limits |
| --- | --- |
| Fetch mode | direct reads static HTML by default. Non-direct fetch modes require deployment enablement, approved targets and resource/spending controls. They can be refused; requesting browser mode does not guarantee JavaScript rendering for any URL. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/web/scrape) |
| Mapping | sitemap can be include, only or skip. URL discovery, include_subdomains and query-string deduplication affect the set, not whether every page was retrieved. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/web/map) |
| Output formats | Select the declared formats. only_main_content strips page chrome; keep the final URL and metadata alongside extracted text. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/web/scrape) |
| Jobs | Crawl and batch-scrape enqueue bounded jobs. Use the documented HTTP method, keep job_id, and inspect jobs/get for results. A timeout or client disconnect is not a cancellation. [Endpoint reference →](https://www.monocrawl.com/docs/endpoints/web/crawl) |



Source availability, ordering and field coverage can change. Inspect warnings and partial-result metadata alongside the rows. See [runnable workflows](https://www.monocrawl.com/docs/workflows), [metric semantics](https://www.monocrawl.com/docs/metric-semantics), [computed fields](https://www.monocrawl.com/docs/computed-fields) and the [pagination matrix](https://www.monocrawl.com/docs/pagination).



For a stateful browser workflow, see [browser sessions](https://www.monocrawl.com/docs/browser-sessions). A browser execution runs page JavaScript; it is not a general Node.js process.



## Match the operation to your task



| Your task | Endpoint | When to use it |
| --- | --- | --- |
| A document file | [`parse`](https://www.monocrawl.com/docs/endpoints/web/parse) | Use the document parser for supported PDF, text and structured text formats. |
| Several pages on one site | [`crawl`](https://www.monocrawl.com/docs/endpoints/web/crawl) | Starts an asynchronous job; read job state and limits instead of treating the enqueue response as finished data. |
| Known URLs in a job | [`batch-scrape`](https://www.monocrawl.com/docs/endpoints/web/batch-scrape) | This web job is distinct from the generic POST /v1/batch wrapper. |
| Read job progress | [`jobs/get`](https://www.monocrawl.com/docs/endpoints/web/jobs/get) | Use the returned job_id; job creation is not available through MCP call_endpoint. |



Explore all documented operations by purpose below. Each endpoint reference contains its accepted parameters and current price.



### Other operations



- [`agent`](https://www.monocrawl.com/docs/endpoints/web/agent)

- [`batch-scrape`](https://www.monocrawl.com/docs/endpoints/web/batch-scrape)

- [`crawl`](https://www.monocrawl.com/docs/endpoints/web/crawl)

- [`extract`](https://www.monocrawl.com/docs/endpoints/web/extract)

- [`jobs`](https://www.monocrawl.com/docs/endpoints/web/jobs)

- [`jobs/cancel`](https://www.monocrawl.com/docs/endpoints/web/jobs/cancel)

- [`jobs/get`](https://www.monocrawl.com/docs/endpoints/web/jobs/get)

- [`map`](https://www.monocrawl.com/docs/endpoints/web/map)

- [`parse`](https://www.monocrawl.com/docs/endpoints/web/parse)

- [`scrape`](https://www.monocrawl.com/docs/endpoints/web/scrape)

- [`sessions`](https://www.monocrawl.com/docs/endpoints/web/sessions)

- [`sessions/close`](https://www.monocrawl.com/docs/endpoints/web/sessions/close)

- [`sessions/create`](https://www.monocrawl.com/docs/endpoints/web/sessions/create)

- [`sessions/execute`](https://www.monocrawl.com/docs/endpoints/web/sessions/execute)

- [`sessions/get`](https://www.monocrawl.com/docs/endpoints/web/sessions/get)



### Accounts and audiences



- [`social-profiles`](https://www.monocrawl.com/docs/endpoints/web/social-profiles)



## Endpoint reference

## web/agent

`GET /v1/web/agent`

Start an asynchronous browser agent: a hosted browser opens the page and the platform's model chooses navigate, click, type or done for up to eight steps. Returns a job; poll /v1/web/jobs/{job_id} for the final page, the extracted answer and every step taken.

*Browser agent*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Page to start from (http/https) — e.g. `https://www.gov.uk/bank-holidays` |
| `prompt` | yes | What the agent should do or find (up to 2,000 characters) — e.g. `Find the date of the next bank holiday in England and Wales` |
| `max_steps` | no | Most actions to take, 1 to 8 (default 8) — e.g. `6` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 10 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/web/agent?url=https%3A%2F%2Fwww.gov.uk%2Fbank-holidays&prompt=Find%20the%20date%20of%20the%20next%20bank%20holiday%20in%20England%20and%20Wales" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": "job_example",
  "status": "queued"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/web/agent#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/web/agent.json)


## web/batch-scrape

`GET /v1/web/batch-scrape`

Scrape up to 25 URLs in one background job and get a job id back immediately; individual URL failures are reported per item and never fail the batch.

*Start an async batch scrape*

| Parameter | Required | Description |
| --- | --- | --- |
| `urls` | yes | Comma-separated list or JSON array of URLs to scrape (max 25 per job) — e.g. `https://example.com,https://www.iana.org` |
| `formats` | no | Comma-separated subset of markdown,text,links (default markdown) Accepted values (comma-separated): markdown, text, links. Case, spaces, hyphens and underscores are interchangeable. — e.g. `markdown` |
| `only_main_content` | no | Render only the main content region of each page (default true) — e.g. `true` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 3 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/web/batch-scrape?urls=https%3A%2F%2Fexample.com%2Chttps%3A%2F%2Fwww.iana.org" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "job_id": "job_example",
  "check": "/v1/web/jobs/job_example",
  "status": "queued",
  "kind": "batch_scrape",
  "params": {
    "urls": [
      "https://example.com/"
    ],
    "formats": "markdown",
    "only_main_content": true
  }
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/web/batch-scrape#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/web/batch-scrape.json)


## web/crawl

`GET /v1/web/crawl`

Start a breadth-first same-site crawl and get a job id back immediately; poll /v1/web/jobs/{job_id} for the collected pages (url, title, markdown excerpt, status).

*Start an async web crawl*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Seed URL to crawl (http/https, public hosts only) — e.g. `https://example.com` |
| `limit` | no | Maximum pages to fetch (default 10, cap 50) — e.g. `10` |
| `max_depth` | no | Link hops from the seed page (default 2, cap 3) — e.g. `2` |
| `include_paths` | no | Comma-separated glob patterns; a discovered path must match at least one. * matches any characters, ^ and $ anchor, everything else is literal — e.g. `^/blog/.*` |
| `exclude_paths` | no | Comma-separated glob patterns; a discovered path matching any of them is skipped — e.g. `/tag/*,/author/*` |
| `formats` | no | Comma-separated subset of markdown,text,links (default markdown) Accepted values (comma-separated): markdown, text, links. Case, spaces, hyphens and underscores are interchangeable. — e.g. `markdown` |
| `only_main_content` | no | Render only the main content region of each page (default true) — e.g. `true` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `limit`: Bound the returned rows to what your task needs. A smaller limit does not necessarily reduce source calls or price; inspect the quote.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 5 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/web/crawl?url=https%3A%2F%2Fexample.com" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "job_id": "job_example",
  "check": "/v1/web/jobs/job_example",
  "status": "queued",
  "kind": "crawl",
  "params": {
    "url": "https://example.com/",
    "limit": 10,
    "max_depth": 2,
    "formats": "markdown",
    "only_main_content": true
  }
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/web/crawl#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/web/crawl.json)


## web/extract

`GET /v1/web/extract`

Deterministic structured extraction from a public page: meta/Open Graph/Twitter tags, parsed JSON-LD blocks, canonical URL, feeds, and heading outline — no AI involved. Fetch modes: direct by default; browser, enhanced and rendered are deployment-gated and off by default. Requested output shapes are unchanged. An unavailable non-direct mode returns 424 rather than silently ignoring the requested mode.

*Extract structured data from a web page*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Page URL to extract from (http/https, public hosts only) — e.g. `https://example.com` |
| `timeout` | no | Fetch budget in milliseconds, clamped to 1000-15000 — e.g. `10000` |
| `fetch_mode` | no | Fetch mode: direct (default) reads static HTML; browser explicitly runs JavaScript in an owned, isolated browser. Enhanced and rendered try direct first and permit configured fallbacks. Non-direct modes require deployment enablement, an approved target and applicable resource or spending limits; otherwise the request is refused. Output formats are unchanged. Accepted values: direct, browser, enhanced, rendered. Case, spaces, hyphens and underscores are interchangeable. — e.g. `direct` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/web/extract?url=https%3A%2F%2Fexample.com" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "url": "https://example.com/article",
  "text": "Illustrative article text."
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/web/extract#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/web/extract.json)


## web/jobs

`GET /v1/web/jobs`

List your asynchronous jobs, newest first, with keyset pagination. Free.

*List async web jobs*

| Parameter | Required | Description |
| --- | --- | --- |
| `limit` | no | Jobs per page (default 25, cap 100) — e.g. `25` |
| `cursor` | no | Opaque cursor from the previous page; omit for the first page |
| `status` | no | Filter by status: queued, running, completed, failed, cancelled (comma-separated for several) Accepted values (comma-separated): queued, running, completed, failed, cancelled. Case, spaces, hyphens and underscores are interchangeable. — e.g. `completed` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `limit`: Bound the returned rows to what your task needs. A smaller limit does not necessarily reduce source calls or price; inspect the quote.
- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/web/jobs" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [],
  "count": 0,
  "cursor": null,
  "has_more": false
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/web/jobs#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/web/jobs.json)


## web/jobs/cancel

`GET /v1/web/jobs/cancel`

Cancel one of your queued or running jobs. A queued job is refunded in full; a running job stops but its charge stands, because upstream work had already begun.

*Cancel a job*

| Parameter | Required | Description |
| --- | --- | --- |
| `job_id` | yes | Job id returned by /v1/web/crawl or /v1/web/batch-scrape — e.g. `job_0123456789abcdef01234567` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/web/jobs/cancel?job_id=job_0123456789abcdef01234567" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": null,
  "kind": null,
  "status": null,
  "error": null,
  "refund_status": null,
  "created_at": null,
  "started_at": null,
  "completed_at": null,
  "credits_charged": 0,
  "credits_refunded": 0,
  "attempts": 0,
  "params": {},
  "progress": {},
  "result": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/web/jobs/cancel#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/web/jobs/cancel.json)


## web/jobs/get

`GET /v1/web/jobs/get`

Fetch one of your jobs by id: status, progress, the result payload once it completes, and the error if it failed. Free.

*Get an async web job*

| Parameter | Required | Description |
| --- | --- | --- |
| `job_id` | yes | Job id returned by /v1/web/crawl or /v1/web/batch-scrape — e.g. `job_0123456789abcdef01234567` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/web/jobs/get?job_id=job_0123456789abcdef01234567" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "id": null,
  "kind": null,
  "status": null,
  "error": null,
  "refund_status": null,
  "created_at": null,
  "started_at": null,
  "completed_at": null,
  "credits_charged": 0,
  "credits_refunded": 0,
  "attempts": 0,
  "params": {},
  "progress": {},
  "result": null
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/web/jobs/get#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/web/jobs/get.json)


## web/map

`GET /v1/web/map`

Discover a site's URLs from its sitemap.xml (one level of sitemap indexes) with same-origin page links as fallback.

*Map URLs on a site*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Site URL to map (http/https, public hosts only) — e.g. `https://example.com` |
| `search` | no | Only return URLs containing this text (case-insensitive) — e.g. `blog` |
| `limit` | no | Maximum URLs to return (default 100, cap 500) — e.g. `100` |
| `sitemap` | no | Sitemap use: include (default: sitemap first, page links as fallback), only, or skip Accepted values: include, only, skip. Case, spaces, hyphens and underscores are interchangeable. — e.g. `include` |
| `include_subdomains` | no | Also include URLs on subdomains of the site — e.g. `false` |
| `ignore_query_parameters` | no | Strip query strings before deduplicating URLs — e.g. `false` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `limit`: Bound the returned rows to what your task needs. A smaller limit does not necessarily reduce source calls or price; inspect the quote.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 3 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/web/map?url=https%3A%2F%2Fexample.com" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_meta": {
    "billing": {
      "charged": 0,
      "list_price": 0,
      "reason": "example"
    }
  },
  "_warnings": [
    "example"
  ],
  "count": 0,
  "discovery": {
    "document_limit_bytes": 0,
    "documents_fetched": 0,
    "max_documents": 0,
    "max_sitemaps": 0,
    "time_limit_ms": 0
  },
  "items": [],
  "limit": 0,
  "origin": "example",
  "sources": [
    "example"
  ],
  "url": "https://example.com/example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/web/map#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/web/map.json)


## web/parse

`GET /v1/web/parse`

Extract text and metadata from HTML, plain text, Markdown, CSV/TSV, JSON, XML and PDF. Read visible text from one static JPEG, PNG or WebP image up to 2 MB and 16 megapixels, including TikTok/Instagram post covers via data.cover_ocr. Empty PDF extraction is uncharged. Office files, archives and unsupported image formats return 422.

*Parse a document*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Public document URL. Also accepts one static JPEG, PNG or WebP image up to 2 MB and 16 megapixels for text extraction; other slides or video frames require separate requests. — e.g. `https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf` |
| `timeout` | no | Fetch budget in milliseconds, clamped to 1000-15000 — e.g. `10000` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 2 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/web/parse?url=https%3A%2F%2Fwww.w3.org%2FWAI%2FER%2Ftests%2Fxhtml%2Ftestfiles%2Fresources%2Fpdf%2Fdummy.pdf" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "detected_type": "image",
  "text": "Example visible text",
  "texts": [
    "Example visible text"
  ],
  "truncated": false
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/web/parse#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/web/parse.json)


## web/scrape

`GET /v1/web/scrape`

Fetch a public web page and return its content as markdown, text, raw HTML, links, and/or page metadata. Fetch modes: direct by default; browser, enhanced and rendered are deployment-gated and off by default. Requested output shapes are unchanged. An unavailable non-direct mode returns 424 rather than silently ignoring the requested mode.

*Scrape a web page*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | yes | Page URL to scrape (http/https, public hosts only) — e.g. `https://example.com` |
| `formats` | no | Comma-separated subset of markdown,html,text,links,metadata (default markdown,metadata) Accepted values (comma-separated): markdown, html, text, links, metadata. Case, spaces, hyphens and underscores are interchangeable. — e.g. `markdown,metadata` |
| `only_main_content` | no | Strip page chrome (nav/header/footer/aside) and return the main content region (default true) — e.g. `true` |
| `timeout` | no | Fetch budget in milliseconds, clamped to 1000-15000 — e.g. `10000` |
| `fetch_mode` | no | Fetch mode: direct (default) reads static HTML; browser explicitly runs JavaScript in an owned, isolated browser. Enhanced and rendered try direct first and permit configured fallbacks. Non-direct modes require deployment enablement, an approved target and applicable resource or spending limits; otherwise the request is refused. Output formats are unchanged. Accepted values: direct, browser, enhanced, rendered. Case, spaces, hyphens and underscores are interchangeable. — e.g. `direct` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/web/scrape?url=https%3A%2F%2Fexample.com" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [
    "example"
  ],
  "content_strategy": "example",
  "content_type": "example",
  "description": "example",
  "final_url": "https://example.com/example",
  "language": "example",
  "markdown": "example",
  "only_main_content": false,
  "status": 0,
  "title": "example",
  "url": "https://example.com/example"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/web/scrape#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/web/scrape.json)


## web/sessions

`GET /v1/web/sessions`

Your browser sessions, newest first, with a cursor to the next page. Expired sessions are marked as they are listed.

*List browser sessions*

| Parameter | Required | Description |
| --- | --- | --- |
| `limit` | no | Sessions per page (default 25, cap 100) — e.g. `25` |
| `cursor` | no | Opaque cursor from the previous page — e.g. `1757100000000` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `limit`: Bound the returned rows to what your task needs. A smaller limit does not necessarily reduce source calls or price; inspect the quote.
- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/web/sessions" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "items": [],
  "count": 0,
  "cursor": null,
  "has_more": false
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/web/sessions#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/web/sessions.json)


## web/sessions/close

`GET /v1/web/sessions/close`

Release the hosted browser and mark the session closed. Closing early does not refund the hold.

*Close a browser session*

| Parameter | Required | Description |
| --- | --- | --- |
| `session_id` | yes | Session id returned by web/sessions/create — e.g. `ws_k3j2h1g0abcd` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/web/sessions/close?session_id=ws_k3j2h1g0abcd" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "session_id": null,
  "kind": null,
  "status": null,
  "url": null,
  "viewer_url": null,
  "expires_at": null,
  "last_activity_at": null,
  "closed_at": null,
  "created_at": null,
  "updated_at": null,
  "execution": null,
  "supplier_status": null,
  "ttl_seconds": 0,
  "activity_ttl_seconds": 0,
  "credits_hold": 0,
  "credits_billed": 0
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/web/sessions/close#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/web/sessions/close.json)


## web/sessions/create

`GET /v1/web/sessions/create`

Open an interactive hosted browser session: returns the session id, status, expiry and the credits held (billed at creation). Up to three live sessions per account; the longest lifetime is fifteen minutes. Drive it with web/sessions/execute; close it with web/sessions/close.

*Open a browser session*

| Parameter | Required | Description |
| --- | --- | --- |
| `url` | no | Page to open first (http/https) — e.g. `https://example.com` |
| `ttl_seconds` | no | Current five-credit session: 30–60 seconds; default 60. Longer sessions require separately reviewed pricing and are rejected before opening. — e.g. `60` |
| `activity_ttl_seconds` | no | Close after this many idle seconds (optional) — e.g. `120` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 5 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/web/sessions/create?url=https%3A%2F%2Fexample.com" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "session_id": "ws_example",
  "status": "active"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/web/sessions/create#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/web/sessions/create.json)


## web/sessions/execute

`GET /v1/web/sessions/execute`

Evaluate JavaScript in the session's page, optionally after navigating: success flag, the returned value, any thrown error, the page URL and the duration.

*Run code in a browser session*

| Parameter | Required | Description |
| --- | --- | --- |
| `session_id` | yes | Session id returned by web/sessions/create — e.g. `ws_k3j2h1g0abcd` |
| `code` | yes | JavaScript evaluated in the page (a promise is awaited); the value is returned as JSON — e.g. `document.title` |
| `url` | no | Navigate here first (optional) — e.g. `https://example.com` |
| `language` | no | Only javascript: code runs in the page over DevTools, not node, python or bash on a host Accepted values: javascript. Case, spaces, hyphens and underscores are interchangeable. — e.g. `javascript` |
| `timeout` | no | Milliseconds to allow, 1000 to 30000 (default 10000) — e.g. `10000` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 1 credit at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/web/sessions/execute?session_id=ws_k3j2h1g0abcd&code=document.title&url=https%3A%2F%2Fexample.com" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "session_id": "ws_example",
  "success": true,
  "language": "javascript"
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/web/sessions/execute#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/web/sessions/execute.json)


## web/sessions/get

`GET /v1/web/sessions/get`

One browser session: status, expiry, credits held and billed, and the supplier's live status while active.

*Browser session status*

| Parameter | Required | Description |
| --- | --- | --- |
| `session_id` | yes | Session id returned by web/sessions/create — e.g. `ws_k3j2h1g0abcd` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** free — 0 credits.

```bash
curl "https://www.monocrawl.com/v1/web/sessions/get?session_id=ws_k3j2h1g0abcd" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "session_id": null,
  "kind": null,
  "status": null,
  "url": null,
  "viewer_url": null,
  "expires_at": null,
  "last_activity_at": null,
  "closed_at": null,
  "created_at": null,
  "updated_at": null,
  "execution": null,
  "supplier_status": null,
  "ttl_seconds": 0,
  "activity_ttl_seconds": 0,
  "credits_hold": 0,
  "credits_billed": 0
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/web/sessions/get#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/web/sessions/get.json)


## web/social-profiles

`GET /v1/web/social-profiles`

Starting from one known profile, the same person or brand's profiles on other platforms, with a confidence score and the evidence behind each match, plus link-in-bio and website URLs.

*Social profile discovery*

| Parameter | Required | Description |
| --- | --- | --- |
| `platform` | yes | Platform of the known profile — e.g. `instagram` |
| `handle` | yes | Handle on that platform — e.g. `nasa` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 15 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/web/social-profiles?platform=instagram&handle=nasa" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [
    "example"
  ],
  "has_more": false,
  "items": [
    {
      "confidence": 0,
      "evidence": [
        "example"
      ],
      "handle": "example",
      "platform": "example",
      "url": "https://example.com/example"
    }
  ],
  "link_in_bio_urls": [],
  "linked_profile_urls": [],
  "partial": false,
  "same_handle_candidates": [
    "example"
  ],
  "source": {
    "handle": "example",
    "platform": "example",
    "url": "https://example.com/example"
  },
  "website_urls": [
    "example"
  ]
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/web/social-profiles#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/web/social-profiles.json)