User guide · MCP server · read-only

Ask your AI chat about Allegro.
Marzi does the looking.

Marzi is a helper you plug into Claude, ChatGPT, Claude Code or Codex. After that you just type questions like “who sells this cheaper than me?” — and your AI reads real Allegro pages and your Marzi account to answer. It never changes anything on Allegro. It only reads.

https://mcp.marzi.ai/mcp

That is the only address you ever need. Paste it where your AI asks for an “MCP server” or “custom connector”.

What is it, in one minute

🧠 Your AI gets eyes

A normal AI chat only knows what it was trained on. With Marzi connected it can open live Allegro search results, product pages, seller shops and your own store data right now, and read the numbers from there.

🔒 Read-only, your account only

Marzi can look but cannot touch: no changing prices, no messages, no orders. And it only sees the Marzi account you signed in with. Nobody else's watchers or products.

👀 Watchers that run without you

Tell the AI “watch this competitor's price every 6 hours” and Marzi keeps checking on its own — even when your chat is closed. Later ask “what changed?” and you get the list.

Things people actually type

Analyze my Allegro store and tell me the 3 things I should fix first.
Who sells this product cheaper than me, including delivery? https://allegro.pl/oferta/…
Is “powerbank 20000 mah” a good product to start selling? What do the top sellers charge?
Watch this offer and tell me when the stock drops below 5.
What did my competitors do this week?

Connect it — pick your AI

Connecting takes about a minute. You sign in once; the AI remembers.

Before you start

  • A Marzi account — the e-mail and password you use on the Marzi site (create one; every new account starts with free requests).
  • In the cabinet, AI Integration is where you choose which functions your AI may call and, for scripts, where the personal token is generated. Nothing chosen yet means every function is on.
  • One of the clients below. Chat apps and coding agents sign in through the browser — no client ID, no secret, no key to paste. Scripts and SDKs send a personal token instead.

The address is the same everywhere: https://mcp.marzi.ai/mcp. Transport: Streamable HTTP. The old SSE transport is not offered.

The cabinet's AI Integration page: the MCP endpoint, the Copy endpoint and Regenerate token buttons, and the client picker with the steps for each
The cabinet, AI Integration → Configure & integrate: the endpoint to copy, the personal token for scripts, and the same steps as here for every client.

Claude.ai and the Claude desktop app

  1. In a chat, open the tools menu (the sliders icon under the message box) and click Add connectors. The same page lives under Settings → Connectors (your profile picture, bottom-left).
    Claude's message box with the tools menu open: Web search, Drive, Gmail and Calendar search, then Add connectors under the cursor
    The tools menu under the message box: Add connectors at the bottom.
  2. On the Connectors page click Add custom connector.
    Settings → Connectors: the list of connectors and the Browse connectors and Add custom connector buttons
    Settings → Connectors → Add custom connector.
  3. Name: Marzi for AI. Remote MCP server URL: https://mcp.marzi.ai/mcp. Leave Advanced settings (client ID and secret) empty — Marzi registers itself. Click Add.
    The Add custom connector dialog: the name Marzi for AI, the URL https://mcp.marzi.ai/mcp, Advanced settings folded, the Add button
    Two fields — the name and the address. Nothing under Advanced settings.
  4. Marzi for AI appears in the list as a custom connector. Click Connect: Marzi's sign-in page opens — type your Marzi e-mail and password, press Allow. Back in the list the row says Connected.
    The Connectors list with the new row: Marzi for AI, the CUSTOM label, https://mcp.marzi.ai/mcp and its Connect button
    The new row. Connect opens Marzi's sign-in page.
    Marzi's sign-in page: the name of the AI app that asks for access, the read-only scope, e-mail and password fields, the Allow access button
    The sign-in page every client opens. It names the app that asks and what it gets — read-only access to your Marzi account.
  5. Back in the chat, open the tools menu again and make sure Marzi for AI is switched on.
    The tools menu with Marzi for AI listed under Web search, its switch turned on
    Marzi for AI in the tools menu, switched on.
  6. Check it works — ask the question below. Claude asks once whether Marzi may run the tool; allow it. A real answer names the sellers with prices from the page and says when the page was read.
Show me who sells https://allegro.pl/oferta/13147824356 and who has the buy box.

Works on Claude Pro, Max, Team and Enterprise. The desktop app shares connectors with claude.ai — set it up once.

After connecting: see what it costs

The cabinet's AI Integration page shows every request your AI made — by day, by function, by client — with its price at the moment of the call, the free requests left and the prepaid balance. A repeated page within minutes and a failed read cost nothing. Set a daily limit there if you want a ceiling: when it is reached, calls are refused until tomorrow and nothing else changes.

The AI Integration dashboard: requests over 30 days split into paid, free trial, cached and errors; traffic; cost; requests left; a chart by day; traffic and cost by kind
The dashboard after a few days of use: paid, trial, cached and failed requests are counted apart — only the first cost money.
Something didn't work?
  • The sign-in page says “wrong e-mail or password”. It wants your Marzi login (the one for the Marzi site), not your Allegro login and not your AI account.
  • The client wants a client ID and a secret. Leave them empty — Marzi registers the client itself when it connects. Only a client with no browser needs a personal token instead.
  • The client only offers SSE. Marzi speaks Streamable HTTP; pick “HTTP” / “Streamable HTTP” where the client asks for a transport, or update the client.
  • The AI says the tool is not available. Open the tools / connectors menu in the chat and switch Marzi on. In Claude Code type /mcp and check it says “connected”.
  • It asks me to sign in again. Access is granted for a while and renewed automatically; if it asks, just sign in — nothing was lost.
  • I want to disconnect. Remove the connector in your AI's settings. Marzi forgets that client at the same moment.

How to ask — a question bank

Copy any of these, change the link or the phrase. The chips say which tool the AI will reach for — you never have to name it.

🛒 Before buying stock

You found a product and wonder whether to sell it.

💰 Pricing

You want to know where your price stands.

  • Who sells this cheaper than me, including delivery? https://allegro.pl/oferta/…
  • What is the real cheapest total for a buyer of this product — item plus delivery?
  • If I match the buy-box price on this card, how far below my current price is that?
  • Which of my products are more than 5% above the cheapest offer on their card?
  • Show the price spread for “słuchawki bluetooth” — cheapest, most popular, and what the top 10 charge.

🥊 Competitors

One seller, one product card, or a whole shop.

  • Who holds the buy box on my product's card, and what do they do differently (price, delivery, Super Seller)?
  • Is https://allegro.pl/uzytkownik/… a trustworthy seller? How many ratings, is it a company?
  • What does this seller sell, and what are their 10 most bought products?
  • Walk this seller's whole shop and tell me how many products they have under 50 PLN.
  • Compare my offer with the leader of the card on price, delivery time and buyers.
  • How many units does the competitor's offer have left, and what does its description promise?

🔎 What buyers see

The search results and category pages, as they are right now.

  • What comes up first for “powerbank 20000 mah”? Which of those are ads?
  • Show new products under 100 PLN in this category, newest first: https://allegro.pl/kategoria/…
  • Search three phrases at once — “patelnia”, “patelnia do naleśników”, “patelnia indukcyjna” — and tell me where the same products repeat.
  • Did Allegro really match my phrase or did it guess? (ask after a search)

🏠 My store

Your products in Marzi's My Products.

👀 Watchers

Things Marzi should keep checking after you close the chat.

  • Watch the price of https://allegro.pl/oferta/… every 6 hours and tell me about moves over 5%.
  • Tell me when this offer has fewer than 5 units left.
  • Warn me if my sneakers fall more than 10 places for “sneakersy męskie big star”.
  • Watch seller X on my product's card and tell me if they go below my price.
  • Every 12 hours check whether this competitor is sold out.
  • What did my watchers catch in the last 24 hours?
  • Show my watchers and how much they cost per month. Pause the price ones until Monday.
  • Delete the watcher on GRYJAK-BUY.

🧮 Estimates (Marzi's calculations)

Things Allegro does not print but Marzi can derive — always labelled as estimates.

  • Roughly how many units a month does this offer sell, and how sure is that number?
  • What is this product card worth per month in revenue, roughly?
  • If I take 10% of this card's buyers at 39.90 PLN, what would that be per month? Label what is fact and what is your calculation.

The tools — what each one finds out, with examples

You never type tool names. You ask a question and the AI picks the tool; this section shows what is possible and what a real answer contains. Each block: what the tool helps you learn → an example question → what the AI answers → the JSON the AI received (a shortened real answer from 14 Sep 2026) → the fields worth knowing.

fast under 2 seconds · slow Marzi opens a real Allegro page, 5–40 seconds (repeats within minutes are instant) · runs by itself Marzi keeps checking after your chat is closed.

Every answer carries a source block — where the data came from, the Allegro page, the time (scraped_at), whether it came from Marzi's short cache — and a note that reminds the AI how to read the numbers. Prices are always PLN. null means “Allegro does not show this”, never zero.

🔍 Looking at Allegro (live pages)

🔎

Search Allegro slow

search_allegro

What a buyer sees when they type a phrase into Allegro's search box — the live listing, card by card. Sort like Allegro does (relevance, cheapest, most expensive, newest, most popular), filter by price and new/used, page through with a cursor, and ask for up to five phrases in one go.

What it helps you find out

  • which products come up for a phrase and in what order — including which ones are paid ads
  • each card's price, delivery info, seller and their feedback %, how many people bought in 30 days, rating
  • how big the listing is: total products and offers, how many pages
  • whether Allegro really matched your phrase (match_type: MAIN) or fell back to loosely related results (FUZZY)

Example

What comes up for “rękawiczki nitrylowe”, most popular first? Which ones are ads?
“4,395 products match; the first page has 20 cards. The top spot is a sponsored Medicov 100-pack at 12.99 PLN (4,698 people bought in 30 days, rating 4.87 from 1,221 ratings) — it repeats at position 15 as an organic result. Three of the first ten cards are ads…”
What the AI received (shortened real answer)
{
 "status": "ok",
 "source": {
  "type": "search",
  "query": "rękawiczki nitrylowe",
  "url": "https://allegro.pl/listing?string=r%C4%99kawiczki%20nitrylowe&order=qd",
  "page": 1,
  "scraped_at": "2026-09-14T19:24:28+00:00",
  "cached": false,
  "page_reads": 1,
  "bytes_read": 1287660
 },
 "currency": "PLN",
 "items": [
  {
   "offer_id": "18135974039",
   "product_id": "1b5a0a6a-7cb7-40e2-a256-c02e4f4653e1",
   "title": "Rękawiczki Nitrylowe CZARNE Jednorazowe Bezpudrowe Medicov Black 100 szt M",
   "url": "https://allegro.pl/oferta/18135974039",
   "category_id": 259899,
   "price": {
    "amount": 12.99,
    "currency": "PLN"
   },
   "original_price": null,
   "price_with_delivery": null,
   "delivery": {
    "free": false,
    "free_return": false,
    "lowest_cost": null,
    "label": "dostawa pojutrze"
   },
   "seller": {
    "login": "MEDICOV",
    "display_name": null,
    "company": true,
    "super_seller": true,
    "positive_feedback_percent": 99.7,
    "storefront_url": "https://allegro.pl/uzytkownik/MEDICOV"
   },
   "flags": {
    "sponsored": true,
    "promoted": true,
    "smart": false,
    "best_price_guarantee": false
   },
   "popularity": {
    "label": "4 698 osób kupiło ostatnio",
    "recent_buyers": 4698,
    "window_days": 30
   },
   "rating": {
    "value": 4.87,
    "count": 1221
   },
   "product_offers_count": 1,
   "parameters": [
    {
     "name": "Rodzaj",
     "value": "nitrylowe"
    },
    "… 4 more"
   ],
   "images": [
    "https://a.allegroimg.com/s360/…",
    "… 11 more"
   ],
   "position": 1,
   "duplicate_of_position": 15
  },
  "… 19 more cards"
 ],
 "next_cursor": "eyJraW5kIjoic2VhcmNo…",
 "has_more": true,
 "page": 1,
 "last_page": 74,
 "total_products": 4395,
 "total_offers": 34181,
 "sort": "popularity",
 "filters": {
  "price_min": null,
  "price_max": null,
  "condition": "all"
 },
 "match_type": "MAIN",
 "note": "Allegro's live search listing at scraped_at. recent_buyers = people who bought in 30 days …"
}

Fields to know

fieldmeaning
items[].flags.sponsoredtrue = a paid slot. Ads sit on top and repeat on every page.
items[].duplicate_of_positionthis ad's offer also appears at that position on the page — count it once
items[].popularity.recent_buyerspeople who bought in the last 30 days (not units)
items[].price_with_deliveryonly when Allegro shows it; null otherwise
items[].seller.login / display_namethe login (used in the shop link) and the shop name Allegro shows when it differs
total_products / total_offers / last_pagethe size of the whole listing, not of this page
next_cursor / has_morepass the cursor back to get the next items; null = the end
match_typeMAIN = a real match; FUZZY = Allegro guessed
🗂️

Category page slow

get_category_products

One page of an Allegro category — the same card shape and filters as search, but starting from a category link instead of a phrase. Good for “what sells in this corner of Allegro”.

What it helps you find out

  • the most popular / cheapest / newest products of a category
  • price levels and who the big sellers are there
  • how large the category is (products, offers, pages)

Example

Show the most popular new powerbanks under 100 PLN in https://allegro.pl/kategoria/powerbanki-252023
“The category has 31,210 products. Filtered to new and under 100 PLN, the most popular page-one cards are: Xiaomi 20000 mAh at 67.99 PLN (1,165 buyers in 30 days)…”
What the AI received (shortened real answer)
{
 "status": "ok",
 "source": {
  "type": "category",
  "url": "https://allegro.pl/kategoria/powerbanki-252023?order=qd",
  "page": 1,
  "scraped_at": "2026-09-14T18:52:51+00:00",
  "cached": false,
  "page_reads": 1
 },
 "items": [
  "… cards in the same shape as search_allegro"
 ],
 "next_cursor": "…",
 "has_more": true,
 "page": 1,
 "last_page": 100,
 "total_products": 31210,
 "total_offers": 65800,
 "sort": "popularity",
 "filters": {
  "price_min": null,
  "price_max": 100.0,
  "condition": "new"
 }
}

Fields to know

fieldmeaning
source.urlthe exact Allegro page with sort and filters applied
filterswhat was applied — check it matches what you asked
items[] …same fields as search_allegro
🏪

A seller's shop slow

get_seller_products

Everything one seller lists, page by page, with the storefront's price-with-delivery. Sorted by relevance (Allegro's own storefront order) it can be walked to the last page. Sorted by popularity Allegro serves only the first page — that is Allegro's rule, so for “their whole assortment ranked by sales” the AI walks the shop in normal order and sorts by buyers itself.

What it helps you find out

  • what a competitor sells and how many products they list
  • their best sellers (first page by popularity, or the whole shop ranked by recent_buyers)
  • their price levels and delivery terms

Example

What does https://allegro.pl/uzytkownik/Baseus-Polska sell, and what are their 10 most bought products?
“The shop lists 512 products (Allegro shows it as ‘Oficjalny sklep Baseus’). Top by buyers in 30 days: 65W GaN charger at 89.00 PLN (812 buyers), …”
What the AI received (shortened real answer)
{
 "status": "ok",
 "source": {
  "type": "seller",
  "url": "https://allegro.pl/uzytkownik/Baseus-Polska",
  "page": 1,
  "scraped_at": "2026-09-14T18:49:37+00:00",
  "cached": false,
  "page_reads": 1
 },
 "items": [
  {
   "offer_id": "…",
   "title": "Ładowarka Baseus 65W GaN",
   "price": {
    "amount": 89.0,
    "currency": "PLN"
   },
   "price_with_delivery": {
    "amount": 89.0,
    "currency": "PLN"
   },
   "seller": {
    "login": "Baseus-Polska",
    "display_name": "Oficjalny sklep Baseus"
   },
   "popularity": {
    "recent_buyers": 812,
    "window_days": 30
   },
   "…": "…"
  },
  "… 59 more"
 ],
 "next_cursor": "…",
 "has_more": true,
 "page": 1,
 "last_page": 9,
 "total_products": 512,
 "sort": "relevance",
 "note": "One storefront page at scraped_at. … Allegro shows a storefront sorted by popularity on its first page only."
}

Fields to know

fieldmeaning
total_productsAllegro's count of the seller's cards
seller.display_namethe shop name shown when it differs from the login
sortrelevance (walkable) or popularity (first page only: has_more true, next_cursor null)
items[].price_with_deliverythe storefront shows it, so it is usually present here

Seller reputation slow

get_seller_profile

What is public about a seller: the Super Seller badge, the share and counts of positive/negative feedback over the last year, whether it is a registered company and its verified name, how many products it lists, and its ten most popular cards.

What it helps you find out

  • can this seller be trusted — feedback % and how many ratings back it
  • is it a company (and which one) or a private person
  • how big it is and what it sells most

Example

Is https://allegro.pl/uzytkownik/MMFashionCenter a trustworthy seller?
“100% positive from 59 ratings in the last year (0 negative); a verified company, Only Sport Marcin Charko; not a Super Seller; 216 products listed. Its most bought card: Nike Air Max Alpha Trainer 5 at 269.99 PLN, 314 buyers in 30 days.”
What the AI received (shortened real answer)
{
 "status": "ok",
 "source": {
  "type": "seller",
  "url": "https://allegro.pl/uzytkownik/MMFashionCenter",
  "scraped_at": "2026-09-14T19:22:50+00:00",
  "page_reads": 2
 },
 "seller": {
  "id": "17954458",
  "login": "MMFashionCenter",
  "name": "MMFashionCenter",
  "company": true,
  "super_seller": false,
  "positive_feedback_percent": 100.0,
  "feedback_count": 59,
  "positive_count": 59,
  "negative_count": 0,
  "company_name": "Only Sport Marcin Charko",
  "company_verified": true,
  "storefront_url": "https://allegro.pl/uzytkownik/MMFashionCenter"
 },
 "products_listed": 216,
 "is_active": true,
 "top_products": [
  {
   "title": "Buty Męskie Sportowe Nike Air Max Alpha Trainer 5 …",
   "price": {
    "amount": 269.99,
    "currency": "PLN"
   },
   "popularity": {
    "recent_buyers": 314,
    "window_days": 30
   },
   "rating": {
    "value": 4.73,
    "count": 335
   }
  },
  "… 9 more"
 ]
}

Fields to know

fieldmeaning
seller.positive_feedback_percent / positive_count / negative_countthe last-year feedback figures as Allegro shows them
seller.company_name / company_verifiedthe registered company behind the login, if Allegro verified it
seller.super_sellerthe Super Seller badge
products_listedhow many cards the shop has
top_products[]ten cards from the storefront's first page by popularity
🏷️

Find by barcode (EAN / GTIN) slow

get_product_by_gtin

Type the 8–14-digit code from the box and get the Allegro product card(s) Allegro links to it, with their offers. With verify Marzi opens the offers and checks the GTIN printed on the page; if the code maps to several different cards the status is ambiguous and the AI must not guess.

What it helps you find out

  • which card on Allegro is “my” product, without searching by words
  • who sells that exact item and at what price
  • whether the code is really published on the offers (gtin_verified) or only associated by Allegro's search

Example

Find 6934177716874 on Allegro — which card is it and who sells it cheapest?
“One card: Powerbank Xiaomi 20000 mAh (GTIN verified on the offer). Cheapest offer seen: eltrox_pl at 61.94 PLN, sponsored, 1,165 buyers in 30 days…”
What the AI received (shortened real answer)
{
 "status": "ok",
 "source": {
  "type": "gtin",
  "query": "6934177716874",
  "scraped_at": "2026-09-14T19:15:17+00:00",
  "page_reads": 1
 },
 "gtin": "6934177716874",
 "currency": "PLN",
 "matches": [
  {
   "product_id": "a3f2463b-942d-4b10-8d6f-3a7b77621d53",
   "product_url": "https://allegro.pl/produkt/a3f2463b-…",
   "title": "Powerbank Xiaomi 20000 mAh czarny 4x USB, szybkie ładowanie 18W",
   "association": "allegro_search",
   "published_gtin": "6934177716874",
   "gtin_verified": true,
   "offers": [
    {
     "offer_id": "18316404730",
     "price": {
      "amount": 61.94,
      "currency": "PLN"
     },
     "seller": {
      "login": "eltrox_pl",
      "super_seller": true
     },
     "popularity": {
      "recent_buyers": 1165,
      "window_days": 30
     },
     "flags": {
      "sponsored": true
     }
    },
    "… more offers"
   ]
  }
 ],
 "note": "Cards Allegro associates with the code; with verify=true the published GTIN of the offers was read. status=ambiguous means several distinct cards — do not pick one."
}

Fields to know

fieldmeaning
statusok / not_found (Allegro only had a fuzzy match) / ambiguous (several distinct cards)
matches[].associationhow the card was linked: allegro_search = Allegro's own match
matches[].published_gtin / gtin_verifiedthe code read from the offer page, and whether it equals the one asked
matches[].offers[]the offers of that card in the common card shape
📦

One offer, the basics slow

get_product

Everything on the offer page that a buyer sees at a glance: price and price with delivery, delivery cost and date, seller and their feedback, how many people bought this offer in 30 days (and, separately, the whole product card), rating and reviews, parameters — plus where this offer stands among the other sellers of the same product (its price rank, the buy box, the leader).

What it helps you find out

  • is this offer selling, and how it compares with the card's other sellers
  • the total price a buyer pays (with delivery) and when it arrives
  • how much of the product's demand this seller takes (share_of_product_pct)

Example

Tell me about https://allegro.pl/oferta/18861837252 — is it selling and how does it stand against others?
“Lavazza Qualita Oro 1 kg from GRYJAK-BUY: 69.79 PLN, 80.28 with delivery. 2,009 people bought this offer in 30 days out of 3,047 on the whole card (66%) — it is the card's leader by buyers, but it does not hold the buy box; price rank 2 of 60 selling offers, 0.1% above the cheapest (69.74).”
What the AI received (shortened real answer)
{
 "status": "ok",
 "source": {
  "type": "offer",
  "url": "https://allegro.pl/oferta/18861837252",
  "scraped_at": "2026-09-14T19:06:25+00:00",
  "cached": true,
  "page_reads": 0
 },
 "data_source": "live",
 "currency": "PLN",
 "offer_id": 18861837252,
 "product_id": "f6b706a3-217c-4172-b0d6-27e6dce0d969",
 "title": "Kawa ziarnista Arabica Lavazza Qualita Oro 1 kg",
 "brand": "Lavazza",
 "category_path": "Allegro / Supermarket / Produkty spożywcze / Kawa / Kawa ziarnista",
 "price": {
  "amount": 69.79,
  "currency": "PLN"
 },
 "price_with_delivery": {
  "amount": 80.28,
  "currency": "PLN"
 },
 "delivery": {
  "free": false,
  "lowest_cost": 10.49,
  "eta_label": "czw. 17 wrz. w punkcie",
  "handling_label": "2 dni robocze"
 },
 "condition": "new",
 "seller": {
  "login": "GRYJAK-BUY",
  "super_seller": false,
  "positive_feedback_percent": 98.5,
  "feedback_count": 134
 },
 "popularity": {
  "recent_buyers": 2009,
  "window_days": 30
 },
 "product_popularity": {
  "recent_buyers": 3047,
  "window_days": 30
 },
 "share_of_product_pct": 65.93,
 "units_30d": 3579,
 "rating": {
  "value": 4.79,
  "count": 105448,
  "reviews_count": 14113
 },
 "product_offers_count": 489,
 "parameters": [
  {
   "name": "Stan",
   "value": "Nowy"
  },
  "… 26 more"
 ],
 "card": {
  "sellers_on_card": 72,
  "selling_on_card": 60,
  "cheapest_price": 69.74,
  "median_price": 92.45,
  "this_offer_price_rank": 2,
  "premium_over_cheapest_pct": 0.1,
  "holds_buybox": false,
  "leader_seller": "GRYJAK-BUY",
  "leader_share_pct": 24.58,
  "super_sellers_on_card": 47,
  "card_buyers_30d": 8174,
  "card_revenue_estimate": 681611.27
 },
 "estimates": null,
 "notes": [
  "popularity.recent_buyers counts people who bought in the last 30 days, as Allegro displays …",
  "…"
 ]
}

Fields to know

fieldmeaning
popularity.recent_buyerspeople who bought THIS offer in 30 days
product_popularity.recent_buyerspeople who bought the whole product card (all sellers)
units_30dunits Allegro states on the page (only some pages show it; null otherwise)
share_of_product_pctthis offer's buyers as a share of the card's buyers
card.this_offer_price_rank / premium_over_cheapest_pctwhere this price sits among the card's offers
card.holds_buybox / leader_sellerwho Allegro features and who sells most
card.card_revenue_estimatea Marzi ESTIMATE (buyers × price), never a fact
rating.count vs rating.reviews_countstar ratings vs written reviews
🔬

One offer, everything (the deep read) slow

get_product_details

The full offer page: everything from get_product plus the exact stock when Allegro prints the number, the barcode, star-by-star rating distribution with the featured review and review aspects, return policy and warranty, breadcrumbs, grouped parameters, the whole description and full-size images, the seller's trading name and feedback counts. The AI calls it only when you ask for one of those things.

What it helps you find out

  • how many units are left (when shown) — the base for “how fast is it selling” watchers
  • the barcode, to match your own product
  • what buyers praise or complain about, star by star
  • return and warranty terms

Example

How many units does https://allegro.pl/oferta/18784227019 have left, and what do the ratings look like?
“350 units in stock (Allegro prints the exact number). 46,281 ratings, 4.92 average: 41,200 five-star, 3,400 four-star… ‘Durability’ is 96% positive in review aspects. The page also states 131 people bought 617 units in 30 days.”
What the AI received (shortened real answer)
{
 "status": "ok",
 "source": {
  "type": "offer",
  "url": "https://allegro.pl/oferta/18784227019",
  "scraped_at": "2026-09-14T19:06:23+00:00",
  "cached": true
 },
 "product": {
  "title": "Rękawice jednorazowe nitrylowe Mercator Medical r. M czarne 100 szt.",
  "price": {
   "amount": 14.64,
   "currency": "PLN"
  },
  "popularity": {
   "label": "131 osób kupiło 617 sztuk",
   "recent_buyers": 131,
   "window_days": 30
  },
  "units_30d": 617,
  "…": "everything get_product gives"
 },
 "stock": {
  "available": 350,
  "exact": true,
  "label": "350 sztuk"
 },
 "gtin": "5906615105510",
 "rating_distribution": {
  "5": 41200,
  "4": 3400,
  "3": 900,
  "2": 300,
  "1": 481
 },
 "featured_review": {
  "rating": 5,
  "text": "Dobre rękawice, mocne…"
 },
 "review_aspects": [
  {
   "name": "Wytrzymałość",
   "positive_pct": 96
  },
  "…"
 ],
 "return_policy": {
  "days": 14,
  "free_return": false
 },
 "warranty": {
  "label": "…"
 },
 "breadcrumbs": [
  "Allegro",
  "Zdrowie",
  "…"
 ],
 "parameter_groups": [
  "…"
 ],
 "description_text": "… up to 20 000 characters …",
 "images_full": [
  "https://a.allegroimg.com/original/…"
 ],
 "seller_extra": {
  "trading_name": "GLOVMED Sp. z o.o.",
  "positive_count": 207,
  "negative_count": 0
 }
}

Fields to know

fieldmeaning
stock.available / exactthe number of units; exact=false means Allegro showed only a range or a label
gtinthe barcode printed on the page
rating_distributionhow many ratings per star
review_aspects[]what Allegro summarises from reviews (e.g. durability 96% positive)
return_policy / warrantyas stated on the page
description_textflattened, capped at 20,000 characters
🥊

Competitors on the same product slow

get_competitors

Every seller of the same product card (the page “all offers of this product”): their price, price with delivery, stock, buyers in 30 days, badges, and who holds the buy box. Sort by the card's order, price, price with delivery or popularity; big cards are paged.

What it helps you find out

  • who is cheaper than you, by item price and by total with delivery
  • who holds the buy box and how far your price is from it
  • how many of the offers are actually selling (selling_on_card) and how much stock they hold

Example

Who else sells https://allegro.pl/oferta/18752936304 and who is cheapest with delivery?
“60 offers on the card, 6 of them with buyers in the last 30 days. Cheapest with delivery: FunshipTroopers at 55.70 PLN (66.19 with delivery), 98 in stock, and it holds the buy box…”
What the AI received (shortened real answer)
{
 "status": "ok",
 "source": {
  "type": "product_card",
  "url": "https://allegro.pl/oferty-produktu/p-34ab3c29-…",
  "scraped_at": "2026-09-14T19:21:04+00:00",
  "page_reads": 1
 },
 "currency": "PLN",
 "product_id": "34ab3c29-afa5-42b2-a913-17032c04ca88",
 "product_offers_count": 60,
 "selling_on_card": 6,
 "buybox_offer_id": "18752936304",
 "rating": {
  "value": 4.81,
  "count": null
 },
 "product_reviews_count": 140,
 "competitors": [
  {
   "offer_id": "18752936304",
   "url": "https://allegro.pl/oferta/18752936304",
   "seller": {
    "login": "FunshipTroopers",
    "company": true,
    "super_seller": false,
    "positive_feedback_percent": 98.5,
    "feedback_count": 403
   },
   "price": {
    "amount": 55.7,
    "currency": "PLN"
   },
   "price_with_delivery": {
    "amount": 66.19,
    "currency": "PLN"
   },
   "stock": 98,
   "popularity": {
    "recent_buyers": 2,
    "window_days": 30
   },
   "flags": {
    "sponsored": false,
    "promoted": true
   },
   "position_on_card": 1,
   "is_buybox": true
  },
  "… 49 more"
 ],
 "truncated": true,
 "next_cursor": "o:50:price_with_delivery",
 "has_more": true,
 "note": "Offers 1-50 of 60 on one Allegro product card at scraped_at …"
}

Fields to know

fieldmeaning
product_offers_countoffers on the card (not verified unique sellers)
selling_on_cardoffers with at least one buyer in 30 days
buybox_offer_id / competitors[].is_buyboxthe offer Allegro features
competitors[].stockunits left, when Allegro shows it
competitors[].position_on_cardthe order Allegro lists them in
next_cursor / has_moremore offers beyond the 50 shown

🏠 Your store (from your Marzi account)

🩺

Store check-up slow

analyze_store

The big one. Takes your products from Marzi's “My Products”, reads each product's card (who else sells it, at what price, who has the buy box) and its search visibility (top-10, beyond the limit, not in the listing at all, declines), and returns problems and opportunities in priority order. Every finding names the exact facts it rests on (field, value, time), shows its arithmetic, suggests an action and says how sure it is. No AI runs inside — it is the same answer every time for the same data.

What it helps you find out

  • what to fix first: overpriced products, lost buy boxes, products invisible in search, rankings that dropped
  • where you have room: cheapest on the card, alone on the card, in the top 10
  • what the data cannot say (unknowns) — an estimate is never passed off as an order count

Example

Analyze my store. What should I fix first?
“3 products checked, 3 cards read. P2 problems: the BIG STAR sneakers are absent from the listing for 1 of 10 tracked searches (Allegro's whole result list was walked); 5 searches declined this week… Opportunity: the Tefal pan is the cheapest of 10 offers on its card with no headroom to the next price. Unknown: sales in units — Marzi has no order data.”
What the AI received (shortened real answer)
{
 "status": "ok",
 "source": {
  "type": "my_products",
  "cached": true
 },
 "currency": "PLN",
 "summary": {
  "products": 3,
  "assessed": 3,
  "cards_read": 3,
  "queries_monitored": 35,
  "queries_measured": 35,
  "top10": 15,
  "outside_top100": 10,
  "not_in_results": 1,
  "declines": 5,
  "needs_attention": 1,
  "monitors_active": 15,
  "problems_by_priority": {
   "P1": 0,
   "P2": 3,
   "P3": 2
  }
 },
 "problems": [
  {
   "priority": "P2",
   "kind": "not_in_results",
   "product_id": 3,
   "product_title": "SNEAKERSY męskie BIG STAR … NN174282 101 41",
   "problem": "1 of 10 measured searches: Allegro's whole listing was walked and the offer is not in it.",
   "evidence": [
    {
     "field": "get_product_positions.positions[big star nn174282].found / organic_scanned",
     "value": "false / 1 of limit 100",
     "observed_at": "2026-09-14T16:53:39+00:00"
    }
   ],
   "derived": [],
   "recommended_action": "Check whether the phrase matches the offer's title and parameters …",
   "expected_impact": "Presence in the results for those phrases.",
   "confidence": "high"
  },
  "… 4 more"
 ],
 "opportunities": [
  {
   "priority": "P3",
   "kind": "cheapest_on_card",
   "product_id": 2,
   "product_title": "Patelnia do naleśników TEFAL UNLIMITED 25cm …",
   "problem": "The seller's offer is the cheapest item price on a card of 10 offers.",
   "evidence": [
    {
     "field": "get_competitors.competitors[mine].price",
     "value": "129.00 PLN",
     "observed_at": "2026-09-14T19:01:04+00:00"
    },
    "…"
   ],
   "derived": [
    "headroom to the next price = 0.00 PLN"
   ],
   "recommended_action": "Interpretation: … test a small increase only if …",
   "confidence": "medium"
  },
  "… 2 more"
 ],
 "products": [
  {
   "product_id": 4,
   "title": "LAVINIA Elegancka … SUKIENKA …",
   "price": {
    "amount": 129.99,
    "currency": "PLN"
   },
   "card_read": true,
   "card_offers": 1,
   "card_cheapest_price": 129.99,
   "my_price_rank": 1,
   "premium_over_cheapest_pct": 0.0,
   "holds_buybox": true,
   "my_recent_buyers": 11,
   "queries_monitored": 10,
   "top10": 4,
   "outside_top100": 0,
   "not_in_results": 0,
   "declines": 4,
   "avg_sponsored_above": 5.7,
   "status": "needs_attention",
   "findings": [
    "alone_on_card",
    "… 3 more"
   ]
  },
  "… 2 more"
 ],
 "unknowns": [
  "Sales volume, revenue and margin: Marzi has no order data; a buyer counter is people who bought …",
  "…"
 ],
 "cards_read": [
  4,
  2,
  3
 ],
 "note": "Deterministic assessment from My Products, the tracked searches and each product's card …"
}

Fields to know

fieldmeaning
summarystore-level counts: products, cards read, searches tracked, top-10, not in results, declines, problems by priority
problems[] / opportunities[]findings, P1 (act now) → P3; each has kind, evidence, derived, recommended_action, expected_impact, confidence
evidence[].field / value / observed_atthe facts — which tool field, its value, when it was seen
products[]per-product standing: price rank, premium over the cheapest, buy box, visibility counts, findings
unknowns[]what this analysis could not establish — the AI should repeat these to you
cards_read[]which products cost a page read (metered)
📋

My products fast

get_my_products

Your list from Marzi's “My Products” (the products you added by link in the cabinet) with a visibility summary per product: how many buyer searches it is tracked in, how many put it in the top 10 / 20 / 100, its average and best position, the biggest rise and fall since the last check.

What it helps you find out

  • which of your products are visible and which are not
  • which one needs attention right now (needs_attention)
  • the ids the AI needs for positions, watchers and the store check-up

Example

List my products and tell me which ones are invisible in search.
“3 products. The LAVINIA dress is tracked in 10 searches: in the top 10 for 4, best position #1 for ‘sukienka elegancka wizytowa’, biggest decline −10 places for ‘sukienka elegancka’ (now #25). The BIG STAR sneakers are outside the top 100 in 9 of 10 searches…”
What the AI received (shortened real answer)
{
 "status": "ok",
 "source": {
  "type": "my_products"
 },
 "currency": "PLN",
 "products": [
  {
   "id": 4,
   "offer_id": 18547900032,
   "url": "https://allegro.pl/oferta/18547900032",
   "title": "LAVINIA Elegancka Klasyczna Wizytowa SUKIENKA …",
   "title_en": "LAVINIA Elegant Classic Dressy DRESS …",
   "brand": "Mabaje",
   "price": {
    "amount": 129.99,
    "currency": "PLN"
   },
   "seller": {
    "login": "womanonline"
   },
   "product_offers_count": 1,
   "status": "active",
   "synced_at": "2026-09-14T16:04:42+00:00",
   "monitoring": {
    "queries_monitored": 10,
    "queries_measured": 10,
    "top10": 4,
    "top20": 6,
    "top100": 10,
    "outside_top100": 0,
    "avg_position": 21.4,
    "best_position": 1,
    "biggest_improvement": {
     "query": "sukienka",
     "delta": 1,
     "position": 44
    },
    "biggest_decline": {
     "query": "sukienka elegancka",
     "delta": 10,
     "position": 25
    },
    "last_checked_at": "2026-09-14T16:56:08+00:00",
    "needs_attention": false
   }
  },
  "… 2 more"
 ],
 "total": 3,
 "next_cursor": null,
 "has_more": false,
 "plan_limit": 10,
 "organic_limit": 100,
 "note": "Products the person added to My Products by link; Marzi does not verify Allegro ownership …"
}

Fields to know

fieldmeaning
products[].monitoring.top10 / top20 / top100 / outside_top100how many of the tracked searches show the product within each limit
products[].monitoring.avg_position / best_positionorganic positions (ads not counted)
products[].monitoring.biggest_decline / biggest_improvementthe search with the largest move and its delta
products[].statusactive / paused / unavailable (the offer ended)
plan_limithow many products your plan may track
organic_limithow deep Marzi looks (100 organic results)
📈

Search positions fast

get_product_positions

For each buyer search you track: your organic position (the place among non-ad results, up to 100), the raw position including ads, how many sponsored slots stood above you, which page that is, the change since the last measurement, the best position ever, and a day-by-day history. Positions are measured once a day.

What it helps you find out

  • where exactly your product shows up for each phrase, and whether it moved
  • whether ads push you down (sponsored_above)
  • when “not found” means the listing ended before you (not_in_listing) or you are simply deeper than 100

Example

Which of my products dropped in search this week, and were ads above them?
“BIG STAR sneakers, ‘sneakersy męskie big star’: organic #93 (raw #117 — 24 sponsored slots above), page 2, unchanged since yesterday. For ‘big star nn174282’ the offer is not in the listing at all: Allegro's result list ended after 1 organic card.”
What the AI received (shortened real answer)
{
 "status": "ok",
 "source": {
  "type": "my_products"
 },
 "organic_limit": 100,
 "products": [
  {
   "product_id": 3,
   "offer_id": 18803353421,
   "title": "SNEAKERSY męskie BIG STAR … NN174282 101 41",
   "price": {
    "amount": 109.99,
    "currency": "PLN"
   },
   "status": "active",
   "monitoring": {
    "queries_monitored": 10,
    "top10": 0,
    "top100": 1,
    "outside_top100": 9,
    "avg_position": 93.0,
    "needs_attention": false
   },
   "positions": [
    {
     "query_id": 31,
     "query": "sneakersy męskie big star",
     "measured": true,
     "found": true,
     "position": 93,
     "raw_position": 117,
     "sponsored_above": 24,
     "page": 2,
     "previous_position": 93,
     "previous_at": "2026-09-13T16:53:09+00:00",
     "change": "same",
     "change_delta": 0,
     "best_position": 93,
     "last_checked_at": "2026-09-14T16:53:14+00:00",
     "next_check_at": "2026-09-15T16:53:14+00:00",
     "organic_scanned": 93,
     "not_in_listing": null,
     "history": [
      {
       "at": "2026-09-14T16:53:14+00:00",
       "found": true,
       "position": 93,
       "raw_position": 117,
       "sponsored_above": 24,
       "page": 2
      },
      "… 1 more"
     ]
    },
    {
     "query_id": 32,
     "query": "big star nn174282",
     "measured": true,
     "found": false,
     "position": null,
     "organic_scanned": 1,
     "not_in_listing": true,
     "…": "…"
    },
    "… 8 more"
   ]
  }
 ],
 "unresolved": [],
 "note": "Organic position = rank among non-sponsored results within the first organic_limit; null = not found …"
}

Fields to know

fieldmeaning
positions[].positionorganic rank; null = not found within organic_limit
positions[].raw_position / sponsored_abovethe rank with ads counted, and how many ads sat above
positions[].change / change_delta / previous_positionmovement since the previous measurement
positions[].not_in_listingtrue = the whole listing was walked and the offer is not in it; false = it is beyond the limit; null = unknown
positions[].organic_scannedhow many organic cards Marzi walked
positions[].history[]daily measurements (with include_history)
🌍

Market overview slow

get_market_overview

Not a live page — Marzi's weekly index of the whole market for a phrase: how many similar products are selling, total buyers, an estimate of money (GMV), price levels, how concentrated it is (do the top 10 take everything?), how many reviews you need to be in the top 10, the competition and accessibility indices. Dated as_of — the AI must say which week.

What it helps you find out

  • is this market worth entering, and how big it is
  • who dominates it and at what price
  • how hard it is to get in (reviews barrier, paid share, entry difficulty)

Example

Is the market for black nitrile gloves 100 pcs worth entering? Who dominates?
“Index of 11 Sep 2026: 6 similar cards selling, 6,242 buyers in 30 days, GMV estimate ~159 k PLN. One card (Mercator Medical, 24.95 PLN, 5,905 buyers, buy box Orgellax) takes almost everything; you would need ~46 reviews to reach the top 10; entry difficulty: high.”
What the AI received (shortened real answer)
{
 "status": "ok",
 "source": {
  "type": "marzi_index",
  "query": "Rękawice nitrylowe czarne 100 szt Mercator M",
  "scraped_at": "2026-09-11"
 },
 "as_of": "2026-09-11",
 "currency": "PLN",
 "understanding": {
  "concept": "Black nitrile gloves, 100 pcs, Mercator M",
  "product_type": "nitrile gloves",
  "brand": "Mercator",
  "categories": [
   {
    "id": 259377,
    "path_en": "Tools / Protective & Work Clothing / Gloves"
   },
   "… 1 more"
  ]
 },
 "market": {
  "similar_products_selling": 6,
  "buyers_30d_total": 6242,
  "gmv_30d_estimate": 158991.92,
  "price_median": 28.49,
  "price_median_buyer_weighted": 24.95,
  "price_p25": 24.95,
  "price_p75": 24.95,
  "top10_revenue_share_pct": 100.0,
  "top5_sellers_share_pct": 100.0,
  "paid_share_top50_pct": 33.3,
  "reviews_to_reach_top10": 46.0,
  "offers_per_top_card": 14.5,
  "competition_index": 69,
  "competition_level": "weak",
  "accessibility_index": 24,
  "entry_difficulty": "high"
 },
 "top_products": [
  {
   "title": "Rękawice jednorazowe nitrylowe Mercator Medical czarne 100 szt.",
   "price": 24.95,
   "buyers_30d": 5905,
   "gmv_30d_estimate": 147329.75,
   "rating": 4.92,
   "reviews_count": 46249,
   "product_offers_count": 634,
   "buybox_seller": "Orgellax",
   "promoted": true
  },
  "… 5 more"
 ],
 "total_matched": 6,
 "note": "Weekly index of Allegro listings dated as_of; product cards, not single offers …"
}

Fields to know

fieldmeaning
as_ofthe index week — quote it
market.similar_products_selling / buyers_30d_totalsize of the market in cards and people
market.gmv_30d_estimatean ESTIMATE of money (buyers × price)
market.price_median / p25 / p75price levels
market.top10_revenue_share_pct / top5_sellers_share_pctconcentration
market.reviews_to_reach_top10 / paid_share_top50_pctthe review barrier and how much of the top is paid
market.competition_index / accessibility_index / entry_difficultyMarzi's indices, 0–100, and the verdict
top_products[]the leading cards with buyers, price, offers and buy box seller

Watchers — Marzi keeps checking for you

A watcher (a “monitor” in the JSON) is a rule like “check this every 6 hours and remember if it changed”. Marzi runs it on its own schedule; your AI chat does not need to be open. Later you ask “what changed?” and get the list of events.

⏰ Schedule

hourly, every 2 hours, every 4 hours, every 6 hours, daily. Shorter than hourly is refused. Position watchers are always daily — Marzi measures search positions once a day.

🎯 Condition

Price: any change, or a move of at least N % / N PLN, a drop, or “below my price”. Stock: any change, below N, sold out. Position: dropped / improved by N places. The first run only records the starting value (the baseline); events start from the second run.

🎟️ Cost

Each run uses operations from your plan (a page Marzi already has in cache costs a quarter). The answer shows estimated_ops_month before you agree, and usage tells you how much of the plan is left. Each plan also caps how many watchers you can have.

Type (type)WatchesEvent it writesShortcut tool
product_pricethe price of one offerprice_changedwatch_product_price
product_stockthe stock of one offerstock_changed, stock_below, out_of_stockwatch_stock
product_positionyour product in all its tracked searchesposition_dropped / position_improvedwatch_product_position
keyword_positionyour product in one search phrasesamewatch_product_position with keyword
competitor_priceone seller's price on the same product cardcompetitor_price_changed, competitor_below_my_pricewatch_competitor
competitor_stockone seller's stock on the same cardcompetitor_stock_changedwatch_competitor with watch: stock

Asking for the same watcher twice gives you the existing one back (status: "exists") — no duplicates. Pausing stops the runs and keeps the history; resuming keeps the rhythm; deleting removes the watcher, its history and its events.

👀 Watcher tools, one by one

💸

Watch a price runs by itself

watch_product_price

Checks one offer's price on a schedule and writes an event when it moves. Tell it how often (hourly … daily) and what counts as a move: at least N % or N PLN; without a threshold every change counts. The first run only records the starting price.

What it helps you find out

  • when a competitor (or your supplier's listing) changes price, and by how much
  • a price history you did not have to collect yourself

Example

Watch the price of https://allegro.pl/oferta/18861837252 every 6 hours and note moves over 5%.
“Done — watcher #24 ‘Lavazza Qualita Oro 1kg price’: every 6 hours, fires on a move of ≥ 5%. First check at 15:04 UTC records the baseline; that is about 120 operations a month (5,622 left on your Growth plan).”
What the AI received (shortened real answer)
{
 "status": "created",
 "monitor": {
  "id": 24,
  "name": "Lavazza Qualita Oro 1kg price",
  "type": "product_price",
  "status": "active",
  "tool": "get_product",
  "target": {
   "url": "https://allegro.pl/oferta/18861837252",
   "offer_id": "18861837252"
  },
  "schedule_minutes": 360,
  "condition": {
   "metric": "change",
   "op": "gte_pct",
   "value": 5.0,
   "event": "price_changed"
  },
  "unit": "PLN",
  "ai_analysis": false,
  "estimated_ops_month": 120,
  "created_at": "2026-09-14T15:04:18+00:00",
  "last_run_at": null,
  "next_run_at": "2026-09-14T15:04:18+00:00",
  "last_error": null,
  "current": null,
  "previous": null,
  "executions": 0,
  "events": 0
 },
 "warnings": [],
 "usage": {
  "used": 4377.5,
  "included": 10000,
  "remaining": 5622.5,
  "plan": "growth"
 },
 "note": "Marzi runs the checks on its own schedule; no AI client needs to stay open. The first run records the baseline …"
}

Fields to know

fieldmeaning
statuscreated, or exists when the same watcher was already there
monitor.schedule_minuteshow often it runs
monitor.conditionmetric / op / value / event — what makes it fire
monitor.estimated_ops_monthwhat it will cost from your plan
monitor.current / previousthe last two observed values with their time and whether the page came from cache
monitor.next_run_at / last_errorwhen it runs next and whether the last run failed
usageoperations used / included / remaining on your plan
📉

Watch stock runs by itself

watch_stock

Checks how many units an offer has left (the deep read of the page) and fires on the condition you choose: stock_below N, out_of_stock, or stock_change (any move). “Below N” and “sold out” fire when the value crosses the line, not on every run while it stays there.

What it helps you find out

  • when a competitor is running out — or restocked
  • how fast an offer sells (stock going down between checks)

Example

Tell me when https://allegro.pl/oferta/18784227019 has fewer than 5 left.
“Watcher #25 ‘Mercator gloves stock’: hourly, fires when stock goes below 5 units. That is up to 720 operations a month — say the word and I'll make it every 6 hours instead (120).”
What the AI received (shortened real answer)
{
 "status": "created",
 "monitor": {
  "id": 25,
  "name": "Mercator gloves stock",
  "type": "product_stock",
  "status": "active",
  "tool": "get_product_details",
  "target": {
   "url": "https://allegro.pl/oferta/18784227019",
   "offer_id": "18784227019"
  },
  "schedule_minutes": 60,
  "condition": {
   "metric": "stock",
   "op": "lt",
   "value": 5,
   "event": "stock_below"
  },
  "unit": "units",
  "estimated_ops_month": 720,
  "next_run_at": "2026-09-14T15:04:19+00:00",
  "current": null,
  "previous": null,
  "executions": 0,
  "events": 0
 },
 "warnings": [],
 "usage": {
  "used": 4377.5,
  "included": 10000,
  "remaining": 5622.5,
  "plan": "growth"
 }
}

Fields to know

fieldmeaning
monitor.condition.metric / op / valuestock lt 5 = below five; op changed = any change
monitor.unitunits
monitor.toolget_product_details — stock needs the deep read, so each run is a page read unless cached
🎯

Watch my search position runs by itself

watch_product_position

Your own product (from My Products) in one search phrase — or in all its tracked phrases when you give no keyword. Daily, because positions are measured once a day. Fires when the organic position drops (or improves, if you ask) by at least N places. A phrase Marzi is not tracking yet is added to My Products for you.

What it helps you find out

  • an alert when you fall out of the top of a search that matters
  • a record of when a climb or fall happened

Example

Warn me if my sneakers fall more than 10 places for “sneakersy męskie big star”.
“Watcher #57: daily check of product #3 for ‘sneakersy męskie big star’, fires on a move of 10 or more places either way. Today's organic position is #93; the first run tonight sets the baseline.”
What the AI received (shortened real answer)
{
 "status": "created",
 "monitor": {
  "id": 57,
  "name": "BIG STAR NN174282 — pozycja sneakersy męskie big star",
  "type": "keyword_position",
  "status": "active",
  "tool": "get_product_positions",
  "target": {
   "url": "https://allegro.pl/oferta/18803353421",
   "offer_id": "18803353421",
   "marzi_product_id": 3,
   "keyword": "sneakersy męskie big star"
  },
  "schedule_minutes": 1440,
  "condition": {
   "metric": "position",
   "op": "moved",
   "value": 10,
   "event": "position_dropped|position_improved",
   "any": [
    "dropped",
    "improved"
   ]
  },
  "unit": "places",
  "estimated_ops_month": 30,
  "next_run_at": "2026-09-14T19:12:44+00:00",
  "current": null,
  "executions": 0,
  "events": 0
 },
 "warnings": [],
 "usage": {
  "used": 4890.0,
  "included": 10000,
  "remaining": 5110.0,
  "plan": "growth"
 }
}

Fields to know

fieldmeaning
monitor.typekeyword_position (one phrase) or product_position (all tracked phrases)
monitor.target.marzi_product_id / keywordwhich product and which phrase
monitor.condition.value / anyplaces, and whether drops, improvements or both fire
monitor.unitplaces
🕵️

Watch a competitor runs by itself

watch_competitor

One specific seller on the same product card as your offer: their price (price_drop, price_change, or below_my_price — compared with your own offer on that card) or their stock. Name the seller by login or by their offer id.

What it helps you find out

  • when the seller you compete with on a card undercuts you
  • when they run low or restock

Example

Watch GRYJAK-BUY on the Lavazza card and tell me if they drop their price.
“Watcher #36 on GRYJAK-BUY's offer of the Lavazza card: every 4 hours, fires on any price drop. ~180 operations a month.”
What the AI received (shortened real answer)
{
 "status": "created",
 "monitor": {
  "id": 36,
  "name": "Spadek ceny GRYJAK-BUY Lavazza Qualita Oro 1kg",
  "type": "competitor_price",
  "status": "active",
  "tool": "get_competitors",
  "target": {
   "url": "https://allegro.pl/oferta/18861837252",
   "offer_id": "18861837252",
   "competitor_offer_id": "18861837252",
   "seller_login": "GRYJAK-BUY",
   "my_offer_id": null
  },
  "schedule_minutes": 240,
  "condition": {
   "metric": "change",
   "op": "lt",
   "value": 0.0,
   "event": "competitor_price_changed"
  },
  "unit": "PLN",
  "estimated_ops_month": 180,
  "next_run_at": "2026-09-14T17:31:40+00:00",
  "current": null,
  "executions": 0,
  "events": 0
 },
 "warnings": [],
 "usage": {
  "used": 2921.0,
  "included": 10000,
  "remaining": 7079.0,
  "plan": "growth"
 }
}

Fields to know

fieldmeaning
monitor.target.seller_login / competitor_offer_idwho is watched
monitor.target.my_offer_idyour offer on the same card — needed for below_my_price
monitor.condition.oplt 0 = a drop; changed = any change; below_my = below your price
monitor.toolget_competitors — the card page is read on each run
🧰

Any watcher, your way runs by itself

create_monitor

The general form behind the four shortcuts: choose the type (six types, see the table above), the link, the schedule, thresholds and conditions, a name. The AI uses it when your request does not fit a shortcut — for example “every 12 hours” or a combined condition.

What it helps you find out

  • exactly the watcher you described, when the shortcuts are too narrow

Example

Every 12 hours check whether this offer is sold out: https://allegro.pl/oferta/…
“Created watcher #58: product_stock, every 12 hours, fires when stock reaches 0 (out_of_stock). ~60 operations a month.”
What the AI received (shortened real answer)
{
 "status": "created",
 "monitor": {
  "id": 58,
  "type": "product_stock",
  "status": "active",
  "tool": "get_product_details",
  "target": {
   "url": "https://allegro.pl/oferta/…",
   "offer_id": "…"
  },
  "schedule_minutes": 720,
  "condition": {
   "metric": "stock",
   "op": "eq",
   "value": 0,
   "event": "out_of_stock"
  },
  "unit": "units",
  "estimated_ops_month": 60,
  "…": "…"
 },
 "warnings": [],
 "usage": {
  "used": 4890.0,
  "included": 10000,
  "remaining": 5110.0,
  "plan": "growth"
 }
}

Fields to know

fieldmeaning
typeproduct_price / product_stock / product_position / keyword_position / competitor_price / competitor_stock
schedulehourly | every 2 hours | every 4 hours | every 6 hours | daily (custom minutes ≥ 60)
threshold_percent / threshold_absolute / valuethe line that makes it fire
status: existsan identical watcher already exists — it is returned instead of a copy

🧾 Managing watchers and reading what changed

🗒️

What changed? fast

get_monitor_events

The list of things your watchers noticed: for each event the value before and after, the change in units and percent, the direction, when it happened, a one-line summary, and (if you switched it on) a short AI explanation. Filter by one watcher, the last N hours, an event type, or unread only; mark them read.

What it helps you find out

  • a digest of everything that moved since you last looked
  • the exact before → after numbers behind every alert

Example

What did my watchers catch in the last 24 hours?
“One event: the Mercator gloves stock went 356 → 350 units (−6, −1.7%) at 16:04 UTC. No price events. Everything else unchanged.”
What the AI received (shortened real answer)
{
 "status": "ok",
 "events": [
  {
   "id": 1,
   "monitor_id": 25,
   "monitor_name": "Mercator gloves stock",
   "monitor_type": "product_stock",
   "event_type": "stock_changed",
   "severity": "info",
   "triggered_at": "2026-09-14T16:04:47+00:00",
   "previous": 356.0,
   "current": 350.0,
   "change": -6.0,
   "change_percent": -1.69,
   "direction": "down",
   "summary": "units: 356 → 350 (-6, -1.7%)",
   "ai_analysis": null,
   "read": false,
   "target": {
    "url": "https://allegro.pl/oferta/18784227019",
    "offer_id": "18784227019"
   }
  },
  "…"
 ],
 "total": 1,
 "next_cursor": null,
 "has_more": false,
 "note": "Events are written only when a monitor's condition held. change = current - previous …"
}

Fields to know

fieldmeaning
events[].event_typeprice_changed, stock_changed, stock_below, out_of_stock, position_dropped, position_improved, competitor_price_changed, competitor_below_my_price, …
events[].previous / current / change / change_percent / directionthe numbers behind the event
events[].summarya one-line human description
events[].ai_analysisoptional explanation (only when ai_analysis was switched on for the watcher)
events[].readwhether you have seen it; mark_read=true flips it
🧾

List, inspect, change, pause, resume, delete fast

list_monitors

list_monitors shows all your watchers (filter by status or type); get_monitor one of them in full with its last values; update_monitor changes the schedule, threshold or name; pause_monitor stops the runs and keeps the history; resume_monitor continues on the old rhythm; delete_monitor removes the watcher, its history and events. All of them see only your own account — a foreign id is simply “not found”.

What it helps you find out

  • what is running, what each costs a month, when it last ran and what it last saw
  • a way to tune or switch off watchers in plain words

Example

Show my watchers. Pause the price ones until Monday, and delete the one on GRYJAK-BUY.
“4 watchers, all active. Paused #33 and #24 (price watchers; history kept, no runs until you resume). Deleted #36 (GRYJAK-BUY) — its events are gone too. Usage this month: 2,660 of 10,000 operations.”
What the AI received (shortened real answer)
{
 "status": "ok",
 "monitors": [
  {
   "id": 33,
   "name": "Price of https://allegro.pl/oferta/18179200866",
   "type": "product_price",
   "status": "active",
   "schedule_minutes": 1440,
   "condition": {
    "metric": "change",
    "op": "changed",
    "event": "price_changed"
   },
   "unit": "PLN",
   "estimated_ops_month": 30,
   "last_run_at": "2026-09-14T17:17:36+00:00",
   "next_run_at": "2026-09-15T17:17:14+00:00",
   "last_error": null,
   "current": {
    "value": 39.99,
    "observed_at": "2026-09-14T17:17:36+00:00",
    "cache_hit": false
   },
   "previous": null,
   "executions": 1,
   "events": 0
  },
  "… 3 more"
 ],
 "total": 4,
 "next_cursor": null,
 "has_more": false,
 "usage": {
  "used": 2659.75,
  "included": 10000,
  "remaining": 7340.25,
  "plan": "growth"
 }
}

Fields to know

fieldmeaning
monitors[].statusactive / paused
monitors[].executions / eventshow many times it ran and how many events it wrote
monitors[].current.value / observed_at / cache_hitthe last value seen, when, and whether the page came from cache (a quarter operation)
monitors[].last_errorwhy the last run failed, if it did — in the closed error vocabulary
usageyour plan's operations: used / included / remaining

Reading the numbers without getting fooled

Allegro shows some numbers and hides others. Marzi passes on exactly what Allegro shows and marks everything else. A good answer from your AI uses four labels:

LabelMeaningExample
FACTRead from an Allegro page or your Marzi data, at a stated time.“Price 67.99 PLN, seen 2026-09-14 19:05.”
DERIVEDMath on facts. The math is shown.“You are 14% above the cheapest: 39.90 / 35.00.”
INTERPRETATIONThe AI's opinion or advice. Could be wrong.“Probably worth lowering the price.”
UNKNOWNAllegro does not show it and there is nothing to derive it from.“Why Allegro moved the offer down — unknown.”

The traps, in plain words

👥 “Bought recently” = people, not items

Allegro's counter says how many people bought in the last 30 days. Not how many pieces, not how much money.

🧮 Two different “popularity” numbers

A product card has its own counter (product_popularity), and each offer on it has one too (popularity). The AI must say which one it quotes.

⭐ Ratings ≠ reviews

rating.count = how many people left stars; reviews_count = written reviews. Different things.

🏬 “158 offers” ≠ 158 sellers

product_offers_count counts offers on a card, not verified unique sellers. To know the sellers, look at the card (competitors tool).

💰 Price vs. price with delivery

Where Allegro shows price_with_delivery, Marzi passes it on; where it is null, the AI must not invent a total.

📢 Ads repeat

Sponsored results (flags.sponsored) sit on top of every page and repeat. duplicate_of_position marks a repeat; counting it twice inflates everything.

🔢 Position = visibility, not sales

Being #3 for a search means people see you third among non-ad results. It says nothing about how many buy.

📅 “As of” matters

Live pages are from right now (or the last few minutes, cached). The market overview is a weekly index — check as_of.

🚫 null means unknown, never zero

If a number is missing, the AI should say “unknown”, not “0”.

What Marzi calculates for you — beyond what Allegro prints

Allegro never prints “this seller sold 617 units this month”. But it prints things that, put together, get you close — and Marzi does that arithmetic for you, always labelled as a calculation, never as an Allegro fact. This is a big part of what makes Marzi more than a page reader.

FigureHow Marzi gets itHow it is labelled
Units sold in 30 days, exactSome offer pages say “131 osób kupiło 617 sztuk”. When Allegro states the quantity, Marzi uses it as it stands.units_30d — a FACT from the page
Units sold in 30 days, estimatedFor offers Marzi checks daily (Spy targets), it reads how far the stock moved between checks and cross-checks it against the buyer counter. Stock also moves for reasons that are not sales, so every figure carries a status (how confident) and a basis (which method).estimates.sold_30d, sold_24h + *_status, basis — ESTIMATE
Revenue of one offerEstimated units × the offer's price.estimates.revenue_30d — ESTIMATE
Revenue of a whole product cardEach offer's buyer counter × its price, summed across the card.card.card_revenue_estimate — ESTIMATE
A seller's share of a product's demandThis offer's buyers ÷ the card's buyers (both are Allegro counters).share_of_product_pct — DERIVED
Size of a marketThe weekly index sums the buyer counters of all similar cards and multiplies by their prices.market.gmv_30d_estimate, buyers_30d_total — ESTIMATE / FACT as of the index week
Units for an offer Marzi is not tracking dailyThe AI can combine the offer's buyers with the units-per-buyer seen on other offers of the same card or market (where Allegro states quantities) and the card's total. That is the AI's own arithmetic on Marzi's facts — a fair estimate, and it must say so.DERIVED by the AI, shown with its formula
How to ask for it: “roughly how many units a month, and how sure are you?” A good answer looks like: FACT 2,009 people bought this offer in 30 days (14 Sep). FACT another offer on the card states 617 units for 131 buyers ≈ 4.7 units per buyer. DERIVED ≈ 9,400 units a month if the ratio holds — a rough estimate, the ratio is from one other seller. If the answer gives you a units number without a label, ask “is that from Allegro or your calculation?”

Limits, waiting, and error messages

⏱️ Why is it slow sometimes?

Opening a real Allegro page takes 5–40 seconds — Marzi loads it in a real browser like you would. Pages are remembered for a while (search pages 10 minutes, product pages 1 hour), so asking the same thing twice is instant.

🎟️ Your plan's allowance

Every question that reads a page uses “operations” from your Marzi plan (a remembered page costs a quarter). Watchers use operations too, on their schedule. Trial: 300 operations and 3 watchers a month; paid plans have more. When the hourly allowance is used up the AI is told “try again in N minutes” — nothing breaks.

🗺️ Allegro's own limits

Allegro shows at most 100 pages of any list, and a seller's shop sorted by popularity only on its first page. Marzi does not pretend otherwise — the AI will tell you “that is as far as Allegro goes”.

What the error messages mean

The AI says…What it meansWhat to do
not_an_offerThe link is not an allegro.pl page of the kind that tool needs (or not allegro.pl at all — Allegro Lokalnie is a different site).Copy the link from the address bar of the Allegro page.
not_foundAllegro has no such offer / shop / card any more, or the product is not on your Marzi list.Check the link; add the product in Marzi's My Products.
allegro_unavailableAllegro would not show that page just now.Wait the minutes it says and ask again. For a long list the pages already read are kept.
rate_limitedThis hour's allowance for that kind of tool is used up.Wait, or upgrade the plan.
invalid_inputThe AI passed something odd (a bad sort, a wrong page cursor, a 5-digit “barcode”).Rephrase; the AI usually fixes it by itself.
backend_error / backend_timeoutSomething on Marzi's side hiccupped.Try again in a minute. It is logged; we look at every one.

Safety, in three sentences

Marzi cannot change anything on Allegro — no prices, no listings, no messages. It reads public pages and your own Marzi data, and that is all the tools can do.
Only your account. The AI sees the Marzi account you signed in with. Another person's watchers, products or events simply do not exist for it — asking for them returns “not found”.
Product titles are not orders. If a listing on Allegro says “ignore your instructions”, Marzi hands it over as text, and your AI is told to treat it as text.

Questions people ask

Do I have to learn the tool names?

No. Ask like you would ask a person. The names on this page are only so you know what exists and what the JSON fields mean.

Does it work on my phone?

Claude: yes — connect once on the web and the Claude phone app uses the same connector. ChatGPT: custom MCP apps are web-only for now (OpenAI's rule), so use ChatGPT in a browser.

Can it tell me how many units a competitor sold?

Yes — with a label. Where Allegro states the quantity on the page, that is an exact units_30d. Where it does not, Marzi estimates units from stock movement between its daily checks (for offers it tracks) and the buyer counter, with a confidence status; and the AI can derive a figure from the offer's buyers and the units-per-buyer seen on the same card or market. Every such number is marked as an ESTIMATE or DERIVED, never as an Allegro fact. See what Marzi calculates.

Can I get the number of people who bought and the revenue of a whole product?

The 30-day buyer counter of the card is an Allegro fact (product_popularity). Revenue is an estimate: buyers × price per offer, summed (card_revenue_estimate); the weekly index does the same for a whole market (gmv_30d_estimate).

Why does the AI sometimes take 30–40 seconds?

It is opening a real Allegro page in a browser, like you would, and some pages (a product card with hundreds of offers, a seller profile) are two reads. Asking the same thing again within minutes is instant — the page is remembered.

Will watchers e-mail me?

Not yet. Ask your AI “what changed?” or look at the bell in the Marzi cabinet. E-mail/Slack delivery is planned.

How much does a watcher cost me?

The answer to every watcher request shows estimated_ops_month (operations per month from your plan) and usage (how much is left). Hourly on a cold page is the expensive end (~720 a month); daily is ~30. A page Marzi already has in cache costs a quarter.

What happens when my plan's allowance runs out?

The AI is told rate_limited with the minutes to wait; watchers skip their run and continue when the allowance is back. Nothing is deleted.

Can I use it with two AI apps at once?

Yes. Each app connects on its own; the watchers you create are the same in all of them, because they live in your Marzi account.

Can my colleague use my connector?

No — the connector is tied to the Marzi account that signed in. Give them their own Marzi login and they connect in a minute.

The AI made a claim I do not see in the data. What now?

Ask it: “Which tool result is that from?” A good answer names the field and the time. If it cannot, it was an interpretation — treat it as an opinion.

Why does the AI say “unknown” instead of a number?

Because Allegro does not show it and Marzi will not invent it: units where no quantity is stated and no stock history exists, the reason for a ranking change, a seller's margin. That “unknown” is the honest answer, and the AI is told to give it.

Can it change my prices or answer buyers for me?

No. Every tool is read-only. Nothing you say to the AI can make Marzi act on Allegro.

Does Marzi see my Allegro password?

No. Marzi never logs in to Allegro on your behalf; it reads public pages. Your Marzi login is the only sign-in, and it goes to Marzi's own page, never through the AI.

Is my data shared with the AI vendor?

The AI you use (Claude, ChatGPT…) receives the tool answers, as it must to answer you — under that vendor's terms. Marzi sends nothing to anyone else.

Which link should I paste?

Any allegro.pl page of the right kind: an offer (/oferta/…), a product card (/produkt/…), a seller (/uzytkownik/…), a category (/kategoria/…). Copy it from the address bar. Allegro Lokalnie links are refused — it is a different marketplace with different counters.

The seller's login and the shop name differ. Which is right?

Both: seller.login is the technical login (in the shop URL), display_name is what Allegro shows as the shop name. The AI should quote the login when linking and the name when talking.

Can it read Allegro in another country (allegro.cz, allegro.sk)?

Not in this release — allegro.pl only.

How old is the data?

Live pages: the moment you asked (or up to 10 minutes for a search page, 1 hour for an offer/card, from cache — scraped_at says exactly). My Products positions: once a day. Market overview: the weekly index, dated as_of.

Where is the technical documentation?

The MCP endpoint is https://mcp.marzi.ai/mcp (Streamable HTTP, OAuth 2.1 with dynamic client registration, PKCE). Health: /health. Every tool describes itself in tools/list; the developer docs are in the Marzi repository under docs/mcp/.