# Segmentation API

Segmentation endpoints aggregate matching posts by a field and return counts instead of the posts themselves. Use them to see the top sites, languages, countries, or entities for a query before (or instead of) fetching content - a quick, cheap way to size up a topic.

## Endpoints

`GET`

```bash
https://api.webz.io/seg_api/news
https://api.webz.io/seg_api/blogs
https://api.webz.io/seg_api/forums
```

## Example

Top languages for posts mentioning bitcoin:

```bash
https://api.webz.io/seg_api/news?token=YOUR_TOKEN&q=bitcoin&field=language
```

```json
{
  "segmentation": [
    { "language": "english", "num_docs": 8341 },
    { "language": "spanish", "num_docs": 1220 }
  ],
  "next": "/seg_api/news?ts=1751713632000&q=bitcoin&field=language&from=10",
  "total_results": 34,
  "more_results_available": 24,
  "requests_left": 988
}
```

## Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `token` | string | - | Your API token |
| `q` | string | `""` | Same query syntax as search - see [Query Syntax](news-blogs-forums-query-syntax) |
| `ts` | integer | 3 days ago | Start of the window, Unix milliseconds. Windows starting more than 31 days back fall back to the 3-day default |
| `field` | string | `thread.site` | Field to aggregate by - see below |
| `from` | integer | `0` | Offset into the buckets; each page returns up to 10 |
| `includeSyndicated` | boolean | `false` | Include syndicated copies |
| `webz_reporter` | boolean | `false` | Include Webz Reporter content |

## Aggregation fields

`thread.site`, `thread.site_suffix`, `thread.site_full`, `thread.site_section`, `thread.site_type`, `thread.country`, `thread.url`, `thread.licensing_agency`, `author`, `language`, `site_category`, `sentiment`, `category`, `rating`, `published`, `locations`, `persons`, `person.positive`, `person.negative`, `person.neutral`, `organizations`, `organization.positive`, `organization.negative`, `organization.neutral`, `trust.bias`, `trust.category`, `trust.source.type`, `trading_symbol.ticker`, `trading_symbol.exchange`

The `topic` field is available only on the News segmentation endpoint. The sentiment and entity fields (`sentiment`, `persons`, `locations`, `organizations`, `person.*`, `organization.*`, `trading_symbol.*`) also aggregate meaningfully only on news - these enrichments are only relevant to news content.

`field=published` returns 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.
- The window can start at most **31 days** back; older `ts` values fall back to the 3-day default. `allowNewsHistory` does not apply.
- Each request costs 1 credit.