> ## Documentation Index
> Fetch the complete documentation index at: https://guides.affiliate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/products/watches — list your product watches

> Retrieve all product watches on your account, with optional metadata filtering and pagination to narrow results to a specific campaign or category.

The `GET /v1/products/watches` endpoint returns all product watches configured on your account. You can paginate through results and filter by any metadata key-value pair you attached to your watches at creation time.

## Endpoint

```
GET /v1/products/watches
```

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer {your_api_key}`.
</ParamField>

## Query parameters

<ParamField query="page" type="integer" default="1">
  The page number to return.
</ParamField>

<ParamField query="per_page" type="integer" default="100">
  The number of watches to return per page.
</ParamField>

<ParamField query="metadata[{key}]" type="string">
  Filter watches by a metadata key-value pair. Replace `{key}` with your custom metadata key. You can include multiple metadata filters in a single request.

  Examples:

  * `?metadata[campaign]=summer_sale`
  * `?metadata[campaign]=summer_sale&metadata[priority]=high`
  * `?metadata[category]=electronics`
</ParamField>

## Example requests

List all watches:

```bash theme={null}
curl --request GET \
  --url 'https://api.affiliate.com/v1/products/watches' \
  --header 'Authorization: Bearer {your_api_key}'
```

Filter by metadata:

```bash theme={null}
curl --request GET \
  --url 'https://api.affiliate.com/v1/products/watches?metadata[campaign]=summer_sale&metadata[priority]=high' \
  --header 'Authorization: Bearer {your_api_key}'
```

## Response

```json theme={null}
{
  "meta": {
    "total": 2,
    "from": 1,
    "to": 2,
    "current_page": 1,
    "last_page": 1,
    "per_page": 100,
    "fields": [],
    "trace_id": "0195cedc-b193-7096-8df4-e7104abf799d"
  },
  "data": [
    {
      "watch_id": "9e84ce37-63be-41cf-87ef-72465fb8ead2",
      "name": "Smart Home Price Drop Watch",
      "target_type": "product",
      "target_id": "1301920351976391947",
      "status": "active",
      "metadata": {
        "category": "electronics",
        "campaign": "summer_sale"
      },
      "rules": [
        {
          "field": "final_price",
          "start_value": 9840,
          "condition": "decrease",
          "threshold": {
            "type": "percentage",
            "value": 15
          }
        },
        {
          "field": "on_sale",
          "start_value": null,
          "condition": "equals",
          "threshold": {
            "type": "value",
            "value": true
          }
        }
      ],
      "notifications": [
        {
          "channel": "webhook",
          "channel_target": "https://example.com/webhooks/watch",
          "frequency": "immediately",
          "enabled": true
        }
      ]
    },
    {
      "watch_id": "9e84ce38-336e-4923-aa55-d23630684e04",
      "name": "Nike Shoe Price Drop Watch",
      "target_id": "1062900034486247121",
      "status": "active",
      "metadata": {
        "category": "footwear",
        "campaign": "summer_sale"
      },
      "rules": [
        {
          "field": "final_price",
          "start_value": 8000,
          "condition": "decrease",
          "threshold": {
            "type": "percentage",
            "value": 10
          }
        }
      ],
      "notifications": [
        {
          "channel": "webhook",
          "channel_target": "https://example.com/webhooks/watch",
          "frequency": "immediately",
          "enabled": true
        }
      ],
      "filters": [],
      "expire_timestamp": 1774751812
    }
  ]
}
```

## Response fields

### `meta` object

<ResponseField name="meta.total" type="integer">
  Total number of watches matching the query.
</ResponseField>

<ResponseField name="meta.from" type="integer">
  Index of the first watch on the current page.
</ResponseField>

<ResponseField name="meta.to" type="integer">
  Index of the last watch on the current page.
</ResponseField>

<ResponseField name="meta.current_page" type="integer">
  The current page number.
</ResponseField>

<ResponseField name="meta.last_page" type="integer">
  The total number of pages.
</ResponseField>

<ResponseField name="meta.per_page" type="integer">
  The number of records per page.
</ResponseField>

<ResponseField name="meta.trace_id" type="string">
  Unique identifier for this request. Include this value when contacting support.
</ResponseField>

### Watch object (`data[]`)

<ResponseField name="watch_id" type="string">
  The unique identifier for the watch. Use this value in path parameters for GET, PUT, and DELETE requests.
</ResponseField>

<ResponseField name="name" type="string">
  The human-readable name you assigned when creating the watch.
</ResponseField>

<ResponseField name="target_type" type="string">
  The watch type: `"product"`, `"asin"`, or `"barcode"`.
</ResponseField>

<ResponseField name="target_id" type="string">
  The product identifier being watched. For multi-target watches, individual watch objects are returned per target.
</ResponseField>

<ResponseField name="status" type="string">
  Current watch status: `"active"`, `"paused"`, or `"completed"`. A watch becomes `"completed"` after its rule is met.
</ResponseField>

<ResponseField name="metadata" type="object">
  The custom key-value pairs attached to the watch.
</ResponseField>

<ResponseField name="rules" type="object[]">
  The rules that trigger a notification. See the [overview](/api-reference/watches/overview#rule-types-and-conditions) for field and condition details.
</ResponseField>

<ResponseField name="notifications" type="object[]">
  The configured notification channels.

  <Expandable title="Notification object">
    <ResponseField name="channel" type="string">
      The notification channel. Currently always `"webhook"`.
    </ResponseField>

    <ResponseField name="channel_target" type="string">
      The webhook URL configured for this watch.
    </ResponseField>

    <ResponseField name="frequency" type="string">
      Notification frequency. Currently always `"immediately"`.
    </ResponseField>

    <ResponseField name="enabled" type="boolean">
      Whether the notification channel is currently active.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="filters" type="object[]">
  Any filters limiting which product listings can trigger the watch. Absent if no filters were set.
</ResponseField>

<ResponseField name="expire_timestamp" type="integer">
  UNIX timestamp of when the watch expires. Absent if the watch uses the default 90-day expiration.
</ResponseField>