# Segmentation API

The segmentation endpoint aggregates matching posts by a field and returns counts instead of the posts themselves - a quick way to see top networks, domains, or authors for a query.

## Endpoint

`GET`

```bash
https://api.webz.io/cyberSeg
```

## Example

Top networks for posts mentioning bitcoin:

```bash
https://api.webz.io/cyberSeg?token=YOUR_TOKEN&q=bitcoin&field=extended.network
```

```json
{
  "segmentation": [
    { "extended.network": "tor", "num_docs": 812 },
    { "extended.network": "telegram", "num_docs": 344 }
  ],
  "requestsLeft": 988,
  "totalResults": 6,
  "moreResultsAvailable": 0,
  "next": "/cyberSeg?token=YOUR_TOKEN&ts=1749121632000&q=bitcoin&field=extended.network&from=6"
}
```

## Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `token` | string | - | Your API token |
| `q` | string | `""` | Same query syntax as search - see [Query Syntax](cyber-api-query-syntax) |
| `field` | string | - | Field to aggregate by - see below |
| `ts` | integer | 1 month ago | Start of the window, Unix milliseconds. Reaches back at most 1 year |
| `from` | integer | `0` | Offset into the buckets; each page returns up to 10 |

## Aggregation fields

`author`, `author_extended.display_name`, `author_extended.user_id`, `author_extended.user_link`, `language`, `published`, `site.domain`, `site.full_domain`, `site.type`, `site.country`, `site.category`, `thread.url`, `thread.published`, `extended.file_type`, `extended.network`, `enriched.category`, `enriched.persons`, `enriched.organizations`, `enriched.cyber_risk.value`, `enriched.cyber_risk.content_risk`, `enriched.cyber_risk.site_risk`, `enriched.cyber_risk.actor_risk`, `enriched.wallet_id.value`, `enriched.cve.value`, `enriched.ssn.value`, `enriched.location.value`, `enriched.email.value`, `enriched.domain.value`, `enriched.phone.value`, `enriched.credit_card.value`, `sys_info.crawled`

Any other field returns `400 Invalid field`.

`published`, `thread.published`, and `sys_info.crawled` return a per-day histogram with `yyyy-MM-dd` keys.

## Limits

- Up to **10** buckets per response; follow `next` (or raise `from`) for more.
- Up to **100** buckets in total per query.
- Each request costs 1 credit.