Haraj Scraper & Monitor

We built Haraj Scraper & Monitor to provide a straightforward way to search classified listings, retrieve seller and ad profiles, and track price or availability changes on Haraj.

Instead of writing custom browser automation or coordinating proxies, you can use our pre-built modes to collect structured data on-demand.

Unofficial Actor: This is an independent tool and is not affiliated with, authorized, or endorsed by Haraj.

---

From Discovery to Automated Monitoring

The Actor is designed around a three-stage workflow that matches how you explore a marketplace: discover listings, inspect targeted records, and monitor specific items for changes over time.

1. Discover listings (discover)

Search by keyword to capture an initial set of listings. This mode acts as your entry point, preserving Haraj's source order and duplicate occurrences.

• Inputs: keyword (required), optional tag refinement, and city refinement.
• Result limit: maxResults controls your target size (defaults to 50, range 50–1000).

2. Inspect a listing (adDetail) or seller (sellerDetail)

Examine the exact entities discovered during search.

• Inspect an ad (adDetail): Fetches a detailed record of a single listing. In addition to core listing info, it retrieves category-specific attributes (including structured properties for car, realEstate, and job listings), images, geographic locations, notes, purchase actions, and comment metadata (such as comment enablement status and counts).
  • Inputs: adUrl (required).
• Inspect a seller (sellerDetail): Fetches a public seller profile and gathers up to 1,000 of their nested ads in source order with duplicate occurrences preserved. Reviews are not collected, and no truncation metadata is exposed.
  • Inputs: sellerUsername (required).

3. Monitor specific ads (monitor)

Track changes to price, availability, and attributes on selected listings over time.

• Creation: Initialize the monitor with 1–10 unique ad URLs to generate a monitorId and save a baseline snapshot as revision 0.
• Continuation: Run subsequent checks using only the saved monitorId. The Actor retrieves new snapshots and compares each listing against its last successfully saved snapshot to emit change lists.
• Deterministic change categories: Detected differences are flagged in a changes array under: availability, status, title, description, price, media, location, seller, tags, or attributes.
• Per-ad execution: Each listing is processed separately. If a single target check encounters a technical failure, the Actor outputs an error row, preserves that ad's last successful snapshot in state, and continues checking the other URLs.

When monitoring, an ad can have three distinct states:

1. Active Observation: The ad is available, returning standard details.
2. Unavailable Observation: The ad is reported as unavailable. The snapshot contains only adId and available: false.
3. Technical Failure: The source check fails due to network or timeout issues. The Actor outputs an error row and preserves the ad's last successfully stored snapshot in state.

---

Quick Start

1. Click Try for free on the Actor page.
2. Under Mode, the dropdown defaults to Discover ads (discover) with the prefilled keyword سيارة (car).
3. Under Discover ads, choose an optional city or region from the pre-defined dropdown to refine your search.
4. Click Start.
5. View your results in the Dataset tab once the run finishes.

For your first run, you can use the prefilled configuration:

{
  "mode": "discover",
  "keyword": "سيارة"
}

---

Input & URL Requirements

To ensure successful runs, please keep the following input rules in mind:

• Keyword Search: Every discovery run requires a search keyword. You can optionally refine the keyword with a free-text tag or select a supported location from the pre-defined city dropdown (which includes Saudi cities as well as regional entries like Kuwait, UAE, and Bahrain).
• Ad URL Formatting: Ad inspection (adDetail) and monitor creation (adUrls) require canonical HTTPS links starting with https://haraj.com.sa/ followed by a numeric public ID beginning with 11 (e.g., https://haraj.com.sa/11184299879). Remove any language prefixes (like /en), query parameters, or trailing hash fragments. Raw ad numbers without a full URL are rejected.

---

Data Structure & Examples

Dataset outputs are saved in the run's default Dataset and categorized under five specific row types: ad, adDetail, seller, monitorObservation, and error.

• Language Preservation: Arabic and mixed-language titles, descriptions, and tag values are preserved exactly as returned.
• Pricing Values: Formatted prices are returned as source display text (e.g., 100 ريال). The Actor does not perform lossy numeric or currency conversions.
• Optional Fields: Highly unstructured listings mean metadata fields vary. Optional properties are omitted from rows when missing, while confirmed 0, false, and empty arrays are explicitly serialized.

Monitor Observation Example (monitorObservation)

The monitoring dataset view includes the monitorId, revision, changes categories, and compares the current snapshot with the previous snapshot.

This is an abridged preview of selected fields, not a complete schema-valid Dataset row.

{
  "type": "monitorObservation",
  "monitorId": "8b23cb41-3da6-46c0-9a25-cb1e6a4b1234",
  "revision": 2,
  "adUrl": "https://haraj.com.sa/11184299879",
  "changes": ["price"],
  "previous": {
    "adId": "11184299879",
    "available": true,
    "title": "حراج السيارات | سيارة نظيفة جدا",
    "formattedPrice": "120000 ريال",
    "updatedAt": "2026-03-01T14:30:00Z"
  },
  "current": {
    "adId": "11184299879",
    "available": true,
    "title": "حراج السيارات | سيارة نظيفة جدا",
    "formattedPrice": "115000 ريال",
    "updatedAt": "2026-03-02T09:15:00Z"
  }
}

• Unavailable Snapshots: If Haraj reports an ad as unavailable, the snapshot contains only "adId": "..." and "available": false (with no title, price, or description fields).
• Technical Failures: If a temporary connection issue prevents an ad from being checked, the Actor emits an error row with type: "error", a diagnostic message, and the target url.

---

Pricing & Proxies

Saudi Residential Proxies Included

Haraj requests are automatically routed through Saudi Arabian residential proxies. Users pay strictly for the Actor’s custom Pay-Per-Event (PPE) operations; platform compute and Saudi managed-proxy expenses are fully included in the Actor's pricing. There is no customer proxy configuration or separate platform/proxy expense to manage.

Custom Pay-Per-Event (PPE) Billing

Charges are applied based on successful operations using these custom events. Refer to the Actor's Pricing tab for current rates.

1. discover-ad (Charged per saved ad during discovery):
   • Successful discovery runs are charged the greater of 50 units or the exact number of ads saved.
   • If a search returns 0 to 50 results, you are billed for exactly 50 events.
   • If a search returns 80 results, you are billed for exactly 80 events.
2. ad-detail (Charged once per successful detail inspection):
   • Billed for exactly one ad-detail event when a complete adDetail row is saved.
3. seller-detail (Charged once per successful seller profile retrieved):
   • Billed for exactly one seller-detail event. This includes nesting up to 1,000 of the seller's ads at no extra charge.
4. monitor-run (Charged once per monitored run):
   • Charged as a flat event when at least one monitored ad check produces a successful observation (whether it is an active snapshot or a billable unavailable status snapshot).

Error and Partial-Check Semantics

• All-Error Checks: Both monitor workflows fail and do not charge monitor-run if all targets fail. An all-error creation run creates no monitor state, while an all-error continuation run leaves the existing state and revision unchanged.
• Partial Checks: If some checked ads succeed and others experience technical failures, the run continues successfully and charges one monitor-run event. Failed targets output error rows, and their last successfully stored snapshots remain in state.
• Complete Inspection Failures: If an inspect (adDetail or sellerDetail) operation fails due to network or source downtime, it outputs a diagnostic error row and the run is not charged.

---

Use with Apify MCP

If you integrate market data into AI assistant workflows, you can connect this Actor directly to compatible clients (such as Claude Desktop) using Apify's hosted Model Context Protocol (MCP) server:

https://mcp.apify.com?tools=crawlstone/haraj-scraper-monitor

Once connected, you can run natural language queries to discover listings, inspect sellers, or trigger monitor checks directly from your AI chat interface.

---

Frequently Asked Questions

Can I modify the URLs in an existing monitor?

No. A monitor supports a fixed, immutable set of 1–10 ad URLs defined when it is created. To track a different list or add more listings, run the Actor with your new URLs to generate a new monitorId.

How do I schedule recurring monitor runs?

Configure an Apify Schedule with your monitorId to run hourly, daily, or at another interval. Ensure your schedule is configured for exclusive execution; concurrent or overlapping runs of the exact same monitorId are unsupported.

Why does my first monitor run show no changes?

The initial run (revision 0) acts as a baseline, capturing the current status of each ad. The changes array is empty, and there is no previous snapshot. Subsequent continuation runs will compare new snapshots against each listing's last successfully saved state.

---

Support

If you need assistance, please open a ticket on this Actor's Discussion tab and include:

• Your Apify Run ID.
• The selected Mode and the Input parameters you provided.
• A description of what you expected versus what occurred.

Please do not share your Apify API Token or other private credentials in public support tickets.