# Watch API

Read what changed on the companies you are watching, with the same rows the signal feed returns.

A watch answers one question: what changed on these companies. Three routes read it, on a bearer key holding `watches:read`.

```bash
curl -s -H 'Authorization: Bearer pxk_…' 'https://prospex.ch/api/v1/watches'
curl -s -H 'Authorization: Bearer pxk_…' 'https://prospex.ch/api/v1/watches/7'
curl -s -H 'Authorization: Bearer pxk_…' \
  'https://prospex.ch/api/v1/watches/7/signals?since=2026-08-01'
```

The index and the detail spend nothing. Signals cost a row each, from the same daily budget every other download surface spends.

Creating a watch, changing what it listens for and adding companies to it stay in the browser. Another account's watch answers **404**.

## Routes

| Name | Path |
| --- | --- |
| watch_index | /api/v1/watches |
| watch_detail | /api/v1/watches/\<str:watch_id> |
| watch_signals | /api/v1/watches/\<str:watch_id>/signals |

## Company roster

The watched companies come from the watch's source: a linked market, or the companies you follow. Read `/api/v1/markets/<id>/companies` for the roster, and use `source_market_id` on the watch to find which market that is.

The detail route reports `company_count` for a quick check that a watch is still populated.

## A watch

| Field | Type | Meaning |
| --- | --- | --- |
| watch_id | integer | The Prospex watch id. |
| watch_name | string | What you called it. |
| watch_url | string | The watch's page in Prospex. |
| source | string | `follows`, `market` or `fixed`. |
| source_market_id | integer\|null | The market a linked watch reads its members from. |
| topics | array | The topic keys this watch listens for. |
| company_count | integer | How many companies it is watching now. |
| paused | boolean | A paused watch still appears in listings but stops alerting. |
| digest_enabled | boolean | Whether it appears in the Monday email. |
| instant_enabled | boolean | Whether it sends same-day alerts. |
| last_refreshed_at | string\|null | ISO 8601 UTC. |

## Signal parameters

| Parameter | Meaning |
| --- | --- |
| since | ISO date or datetime. Only signals recorded after it. |
| type | Topic keys, repeated or comma-separated. Defaults to the watch's own topics. |
| limit | Rows per page, up to 100. |
| cursor | Opaque. Follow `next_url` instead of building one. |

A parameter this route does not accept answers **400 `unknown_parameter`**.

Rows are newest first. The cursor is keyset-based, so new signals added between two requests are never skipped. Maximum page size 100.

## Topics

| Key | What it covers |
| --- | --- |
| company_structure | Company structure |
| leadership | Leadership and teams |
| products_positioning | Products and positioning |
| growth_finance | Growth and finance |
| company_news | Company news |

Omit `type` to get every topic the watch listens for. Pass one or more to narrow within that set.

A signal row is a signal-feed row, field for field, so the [signal feed page](https://prospex.ch/docs/feed/) has the field table.