> For the complete documentation index, see [llms.txt](https://docs.webz.io/llms.txt). Any docs page is also available as markdown at `https://docs.webz.io/markdown/<environment>/<slug>`.

# Discover (Pay as you go)

Discover is a ready-made feed of dark web posts that mention your organization's domains. There is no query to write: you verify your domains once, and every call returns the newest posts about them.

> [!NOTE]
> Discover is available to **pay-as-you-go accounts** on the **main API token** only. Contract plans use the [search endpoint](https://docs.webz.io/docs/webz/dark-web-api-endpoints) instead. Any other token returns `401`.

## Endpoint

`GET`

```bash
https://api.webz.io/darkwebDiscover?token=YOUR_TOKEN
```

`POST` with the same parameters is also accepted. Authenticate with `token` or an `Authorization: Bearer YOUR_TOKEN` header.

## Before you start: verify your domains

Discover only searches domains you have verified in the playground **Assets** page ([app.webz.io/playground/assets](https://app.webz.io/playground/assets)), by adding a DNS TXT record or, for your primary domain, by email approval. A request that names an unverified domain returns `403` with `X-RateLimit-Reason: unverified_asset`; an account with no verified domain gets the same `403`.

## Parameters

| Parameter | Required | Default | Description |
| --- | --- | --- | --- |
| `token` | Yes | — | Your main API token (or the `Authorization` header). |
| `domain` | No | all verified domains | Which verified domains to search. Repeat the parameter or separate values with commas, up to **20**. Each must equal a verified domain or sit under one (`sub.example.com` under `example.com`). |
| `size` | No | `5` | Posts per page, `1`-`100`. |
| `from` | No | `0` | Offset for paging. Use the `next` URL instead of computing it. |
| `ts` | No | 3 months ago | Return posts crawled at or after this time, epoch milliseconds UTC - as on `/cyberFilter`. Capped at **2 years** back. |

Posts are sorted by publication date, newest first. Any other value for `size` or `from` returns `400`.

```bash
curl "https://api.webz.io/darkwebDiscover?token=YOUR_TOKEN&domain=example.com&ts=1759276800000"
```

## Response

```json
{
  "posts": [ ... ],
  "totalResults": 42,
  "moreResultsAvailable": 37,
  "next": "/darkwebDiscover?token=YOUR_TOKEN&domain=example.com&size=5&from=5&ts=1759276800000",
  "cost": 0.75,
  "balance": 4.25
}
```

| Field | Type | Description |
| --- | --- | --- |
| `posts` | array | Dark Web API posts - the same fields as [Post Data Fields](https://docs.webz.io/docs/webz/dark-web-api-data-fields), with links hidden (see below). |
| `totalResults` | integer | Posts matching your domains in the time window. |
| `moreResultsAvailable` | integer | Posts still available after this page. |
| `next` | string | Relative URL of the next page, or `null` when there is none. Append it to `https://api.webz.io`. It carries the same domains and time window, so every page of one feed covers the same span. |
| `cost` | number | What this page cost, in USD. |
| `balance` | number | Your balance after the charge, in USD. |

### Hidden links

Discover shows *that* your domain is being discussed, not where. Link fields (`url`, `thread.url`, `author_extended.user_link`, `main_image`, `external_links`, `cache_link`, and similar) are `null`, and any web or `.onion` address inside text fields is replaced with `[hidden]`. The [search endpoint](https://docs.webz.io/docs/webz/dark-web-api-endpoints) on a contract plan returns the full posts - contact sales@webz.io.

## Pricing

Every page is a billed call:

| | Price |
| --- | --- |
| Per request | **$0.25** |
| Per post returned | **$0.10** |

A page of 5 posts costs $0.75; an empty page costs $0.25. Before the search, your balance must cover a **full** page at the requested `size` (`$0.25 + $0.10 × size`); after it, only the posts actually returned are charged.

## Errors

Errors are plain text.

| Status | `X-RateLimit-Reason` | When |
| --- | --- | --- |
| `400` | | `size` outside `1`-`100`, negative `from`, an invalid domain, or more than 20 domains. |
| `401` | | Unknown token, an additional token, or an account that is not pay as you go. |
| `402` | `insufficient_balance` | Balance below the price of a full page. Top up at [app.webz.io/playground/settings/credits](https://app.webz.io/playground/settings/credits). |
| `403` | `unverified_asset` | A requested domain is not verified, or you have no verified domain. |
| `429` | `rate_limit` | More than about 1 request per second. |
| `429` | `inactive_user` | Your account email is not verified yet. |
| `500` | | Internal error - retry. |

## Related documentation

- [Dark Web Answers API](https://docs.webz.io/docs/webz/dark-web-answers-api) - ask questions about what Discover surfaces.
- [Post Data Fields](https://docs.webz.io/docs/webz/dark-web-api-data-fields)
- [Errors, Rate Limits & Credits](https://docs.webz.io/docs/webz/dark-web-api-errors-limits)

