---
title: "Watch a dataset"
method: POST
path: "/v1/dataset-watches"
---

# Watch a dataset

`POST /v1/dataset-watches`

## Request

- Base URL: `https://api.ploti.ai`
- URL: `https://api.ploti.ai/v1/dataset-watches`
- Auth: HTTP bearer

Be told each time a dataset gets a new version: Ploti sends a dataset.updated event to the member's webhooks (create_webhook makes one) with the dataset's id, the new version and when it went live. Use it to have an agent check new rows for what the user is after, such as new permits matching their criteria, instead of polling. Watch a dataset find_data found; one the workspace's coverage or plan does not open cannot be watched. Watching again changes nothing. A member may watch 100 datasets.

## Request body

- object
  - `datasetId` string, required: Which dataset, by the id find_data gives for it; list_dataset_watches repeats the ids being watched.

## Response `201`

Created

- object
  - `watch` object, required
    - `datasetId` string, required
    - `title` string, required
    - `place` string, nullable, required
    - `since` string, required: When the watch began.

## Other responses

- `401`: The credential is missing or not valid.
- `413`: payload_too_large: the body is over 256 KB (2 MB for /v1/tools).
- `415`: unsupported_media_type: a body was sent without Content-Type: application/json.
- `429`: rate_limited: this credential is over its rate. Retry after the Retry-After header's seconds.
- `500`: internal: Ploti failed. Retry; if it keeps happening, contact support.
- `default`: Refused: nothing was done. The code says why and the links say where the person acts on it.

---

[API](https://skmtc.dev/ploti/apis/ploti-api.md) · [All operations](https://skmtc.dev/ploti/apis/ploti-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ploti/apis/ploti-api/revisions/8c2c91c72d52?raw)