# Price Monitoring Bot (`mykhailo_r/price-monitoring-bot`) Actor

Scrapes product prices and availability from a page, compares them with the previous run and optionally sends a Telegram alert when something changes.

- **URL**: https://apify.com/mykhailo_r/price-monitoring-bot.md
- **Developed by:** [Mykhailo Rudiak](https://apify.com/mykhailo_r) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Price Monitoring Bot

Monitor prices, availability and new products on any product-catalog page and get a **Telegram alert** when something changes.

You point the Actor at a catalog page, tell it which CSS selectors hold the title, price (and optionally availability) of each product, and schedule it. It remembers what it saw last time and tells you only what changed.

### How it works

1. **First run – baseline.** The Actor scrapes the page(s) and saves the result as the baseline state. No alert is sent. Every product gets `changeType: "new"` in the Dataset.
2. **Every next run – comparison.** The Actor scrapes again and compares each product with the saved state. It reports only real changes:
   - 🆕 a product that was not in the previous run,
   - 💰 a price change,
   - 📦 an availability change.
3. If there are changes and `notifyOnChange` is on, one Telegram message with the list of changes is sent. Without a Telegram token and chat ID the message is only written to the run log.
4. The new result replaces the saved state.

The state is stored in a named Key-Value Store (`price-state`) in your account, separately for each `startUrl`, so it survives between runs. To get regular alerts, run the Actor on an [Apify Schedule](https://docs.apify.com/platform/schedules). Deleting that store resets the baseline.

Pages are rendered in headless Chromium (Playwright), so JavaScript-rendered catalogs work too.

### Input

Only `startUrl` is required. The default selectors match [books.toscrape.com](https://books.toscrape.com/) and are only a starting point – set them for your site.

| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| `startUrl` | string | **yes** | URL of the catalog page to monitor. | `https://books.toscrape.com/` |
| `itemSelector` | string | no | CSS selector matching one product card. Default: `article.product_pod`. | `li.product` |
| `titleSelector` | string | no | Selector of the title, relative to the card. The element's `title` attribute is used if present, otherwise its text. Default: `h3 a`. | `h2.product-title` |
| `priceSelector` | string | no | Selector of the price, relative to the card. Default: `p.price_color`. | `span.price` |
| `availabilitySelector` | string | no | Selector of the availability text, relative to the card. Leave empty if the site has none – `availability` will then be `null`. No default. | `p.instock.availability` |
| `linkSelector` | string | no | Selector of the link to the product page, relative to the card. Its URL is used as the product's identity between runs. Set it when the title is not a link. No default. | `a.product-link` |
| `maxItems` | integer | no | Maximum number of products checked **in total, across all pages**. Default: `12`. | `100` |
| `maxPages` | integer | no | Maximum number of pages to scrape. Needs `nextPageSelector`. Default: `1`. | `3` |
| `nextPageSelector` | string | no | Selector of the "next page" link or button. Pagination stops when it is not found, or at `maxPages` / `maxItems`. If empty, only the first page is scraped. | `li.next a` |
| `navigationTimeoutSecs` | integer | no | Timeout for page navigation and for waiting for the product list. Default: `15`. | `30` |
| `telegramBotToken` | string (secret) | no | Bot token from [@BotFather](https://t.me/BotFather). | `123456:ABC-DEF...` |
| `telegramChatId` | string | no | ID of the chat that receives alerts. | `123456789` |
| `notifyOnChange` | boolean | no | Send the alert when changes are found. Default: `true`. The Dataset is written either way. | `true` |
| `proxyConfiguration` | object | no | Apify Proxy or your own proxy URLs. If not set, the Actor connects directly. | `{"useApifyProxy": true}` |

#### Setting up Telegram

1. Message **@BotFather** in Telegram, send `/newbot` and copy the token.
2. Send any message to your new bot.
3. Open `https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates` and find `"chat":{"id": ...}` – that is your chat ID.
4. Put both values into `telegramBotToken` and `telegramChatId`.

Telegram messages are limited to 4096 characters; longer change lists are truncated.

### Output (Dataset)

One item per product per run:

| Field | Type | Description |
|---|---|---|
| `title` | string | Product title. |
| `price` | number | Price as a number (`£1,234.50` → `1234.5`). If the text cannot be parsed, the raw text is kept as a string. |
| `currency` | string | null | ISO code detected from the currency symbol (see limitations), or `null` if unknown. |
| `availability` | string | null | Availability text. `null` if `availabilitySelector` is not set; empty string if it is set but not found on the card. |
| `changeType` | string | Result of the comparison with the previous run (see below). |
| `previousPrice` | number | null | Previous price when the price changed, otherwise `null`. |
| `checkedAt` | string | UTC timestamp of the run, ISO 8601. |

`changeType` values:

| Value | Meaning |
|---|---|
| `new` | Product was not in the previous run. On the very first run all products are `new`, but no alert is sent. |
| `price_changed` | Price (or currency) differs from the previous run. |
| `availability_changed` | Availability text differs from the previous run. |
| `price_and_availability_changed` | Both changed. |
| `unchanged` | Nothing changed. |

Example item:

```json
{
  "title": "Ivysaur",
  "price": 79.0,
  "currency": "GBP",
  "availability": null,
  "changeType": "price_changed",
  "previousPrice": 87.0,
  "checkedAt": "2026-11-17T16:04:04+00:00"
}
```

Currency symbols recognized: `£` GBP, `€` EUR, `$` USD, `¥` JPY, `₴` UAH, `₹` INR, `zł` PLN, `Kč` CZK, `CHF`.

### Known limitations

- **Currency comes from the symbol only.** `$` is always read as `USD` – USD, CAD, AUD and others cannot be told apart. `¥` is always read as `JPY` (it is also used for CNY). Prices with other or no symbols get `currency: null`.
- **Availability is `null` unless you set `availabilitySelector`.** The Actor does not guess it. A status that exists only as a CSS class (for example `instock` on the card) cannot be read.
- **Set `linkSelector` when the title is not a link, and do not change it between runs.** Products are matched between runs by their URL; if there is no link, by title. Titles are not always unique, so without a link two different products with the same title can be confused. Adding or changing `linkSelector` on an already monitored page changes the product identities, and the next run will report all products as new.
- **Monitor stable catalog pages only.** Blocks such as "popular right now" or "top items" whose content rotates will produce constant `new` alerts.
- **Changing `maxItems`, `maxPages` or the selectors between runs changes the set of products** and is reported as new products. Choose them once per monitored page.
- **Disappeared products are not reported.** The Actor alerts on new products, price changes and availability changes, not on removed products.
- **A failed run does not change the state.** If a page after the first one fails to load, the run fails and the saved state stays as it was.
- One run monitors one `startUrl` with one set of selectors. Logins, forms and other page interaction are not supported.

### Example

**Goal:** get a Telegram message when a Pokémon on [scrapeme.live](https://scrapeme.live/shop/) gets cheaper.

Input:

```json
{
  "startUrl": "https://scrapeme.live/shop/",
  "itemSelector": "li.product",
  "titleSelector": "h2.woocommerce-loop-product__title",
  "priceSelector": "span.price",
  "linkSelector": "a.woocommerce-LoopProduct-link",
  "nextPageSelector": "a.next.page-numbers",
  "maxPages": 3,
  "maxItems": 100,
  "telegramBotToken": "<your bot token>",
  "telegramChatId": "<your chat id>"
}
```

Run it once – it stores the baseline of 48 products and sends nothing. Then put the Actor on a schedule (for example every 6 hours). When the price of a product changes, you receive a message like:

```
📊 Price Monitor: changes detected

💰 Ivysaur: price changed 87.0 → 79.0
```

The alert lists every price change, up or down. To work only with price drops, open the Dataset and filter items where `price < previousPrice`.

### Proxy

Many shops block automated traffic. For sites with bot protection or rate limits, enable **Apify Proxy** in `proxyConfiguration` (for example `{"useApifyProxy": true}`; for strictly protected sites choose the residential proxy group). You can also pass your own proxy URLs with `{"useApifyProxy": false, "proxyUrls": ["http://user:pass@host:port"]}`.

# Actor input Schema

## `startUrl` (type: `string`):

URL of the page with the product list to monitor.

## `itemSelector` (type: `string`):

CSS selector matching one product card on the page.

## `titleSelector` (type: `string`):

CSS selector (relative to the product card) for the product title. The `title` attribute is used if present, otherwise the element text.

## `linkSelector` (type: `string`):

Optional CSS selector (relative to the product card) of the link to the product page. Its href is used as a stable product identity when comparing runs. Useful when the title is not a link. If empty or not found, the title link or the title text is used.

## `priceSelector` (type: `string`):

CSS selector (relative to the product card) for the price.

## `availabilitySelector` (type: `string`):

CSS selector (relative to the product card) for the availability text. Leave empty if the site has no explicit availability: the Dataset will then contain availability: null.

## `maxItems` (type: `integer`):

Maximum total number of products to check (across all pages).

## `maxPages` (type: `integer`):

Maximum number of pages to scrape. Pagination only works when the next page selector is set.

## `nextPageSelector` (type: `string`):

CSS selector of the "next page" link or button. Leave empty to scrape only the first page.

## `navigationTimeoutSecs` (type: `integer`):

Timeout for page navigation and for waiting for the product list.

## `proxyConfiguration` (type: `object`):

Optional. Select Apify Proxy or provide your own proxy URLs. If not set, the Actor connects directly.

## `telegramBotToken` (type: `string`):

Bot token from @BotFather. If empty, alerts are only written to the log.

## `telegramChatId` (type: `string`):

Chat ID that receives the alerts. If empty, alerts are only written to the log.

## `notifyOnChange` (type: `boolean`):

Send the alert (or log it in demo mode) when changes are detected.

## Actor input object example

```json
{
  "startUrl": "https://books.toscrape.com/",
  "itemSelector": "article.product_pod",
  "titleSelector": "h3 a",
  "priceSelector": "p.price_color",
  "maxItems": 12,
  "maxPages": 1,
  "nextPageSelector": "li.next a",
  "navigationTimeoutSecs": 15,
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "notifyOnChange": true
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "startUrl": "https://books.toscrape.com/",
    "nextPageSelector": "li.next a",
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("mykhailo_r/price-monitoring-bot").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "startUrl": "https://books.toscrape.com/",
    "nextPageSelector": "li.next a",
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("mykhailo_r/price-monitoring-bot").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startUrl": "https://books.toscrape.com/",
  "nextPageSelector": "li.next a",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call mykhailo_r/price-monitoring-bot --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,mykhailo_r/price-monitoring-bot"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/gLIn9IbfMpIj6bt18/builds/8Tf0UxWNMacBGESHC/openapi.json
