{
  "data": {
    "id": "ya7w1ICCTwMyXNlt8",
    "actId": "wmIjD3q20aDLjIqvx",
    "userId": "BNsQ2cO8h74hddVli",
    "startedAt": "2026-11-16T17:41:21.757Z",
    "finishedAt": "2026-11-16T17:41:23.632Z",
    "status": "SUCCEEDED",
    "meta": {
      "origin": "CI",
      "githubActionsRunUrl": "https://github.com/architek-earth/apify-actors/actions/runs/43920906423"
    },
    "stats": {
      "durationMillis": 1772,
      "runTimeSecs": 1.772,
      "computeUnits": 0.001968888888888889,
      "imageSizeBytes": 339275776
    },
    "options": {
      "useCache": true,
      "betaPackages": false,
      "memoryMbytes": 4096,
      "diskMbytes": 8192
    },
    "exitCode": 0,
    "inputSchema": "{\n  \"title\": \"Four Square NZ weekly specials\",\n  \"type\": \"object\",\n  \"schemaVersion\": 1,\n  \"properties\": {\n    \"storeId\": {\n      \"title\": \"Store\",\n      \"type\": \"string\",\n      \"editor\": \"textfield\",\n      \"description\": \"A Four Square store page URL, for example https://www.foursquare.co.nz/south-island/southland-and-stewart-island/stewart-island, or its store GUID. Blank selects Four Square Ohope Beach.\"\n    },\n    \"searchTerms\": {\n      \"title\": \"Keywords\",\n      \"type\": \"array\",\n      \"editor\": \"stringList\",\n      \"default\": [],\n      \"description\": \"Optional. Keep only specials whose name contains every word of a keyword, for example milk or pams cheese. Each keyword is its own query. Leave empty for all specials.\"\n    },\n    \"categories\": {\n      \"title\": \"Departments\",\n      \"type\": \"array\",\n      \"editor\": \"stringList\",\n      \"default\": [],\n      \"description\": \"Optional. Keep only specials in these departments: Beer, Cider & Wine; Chilled & Frozen; Cleaning, Health & Body; Fruit & Vegetables; Meat & Seafood; Pantry & Grocery.\"\n    },\n    \"maxItemsPerQuery\": {\n      \"title\": \"Maximum products per query\",\n      \"type\": \"integer\",\n      \"minimum\": 0,\n      \"maximum\": 100000,\n      \"default\": 100,\n      \"description\": \"Cap per keyword, department or the all-specials query. 0 means no cap; time and spending limits still apply.\"\n    },\n    \"preview\": {\n      \"title\": \"Free preview\",\n      \"type\": \"boolean\",\n      \"default\": true,\n      \"description\": \"Free on every run: one page and up to 10 products, never charged. Turn off for paid collection.\"\n    },\n    \"continuePreviousRun\": {\n      \"title\": \"Continue previous run\",\n      \"type\": \"boolean\",\n      \"default\": false,\n      \"description\": \"Paid only. Picks up from the previous run's saved checkpoint, once.\"\n    },\n    \"previousStoreId\": {\n      \"title\": \"Previous run key-value store\",\n      \"type\": \"string\",\n      \"editor\": \"resourcePicker\",\n      \"resourceType\": \"keyValueStore\",\n      \"resourcePermissions\": [\n        \"READ\"\n      ],\n      \"description\": \"The previous run's default key-value store (holds CHECKPOINT and CHECKPOINT_META). Not a supermarket store ID.\"\n    },\n    \"previousQueueId\": {\n      \"title\": \"Previous run claim queue\",\n      \"type\": \"string\",\n      \"editor\": \"resourcePicker\",\n      \"resourceType\": \"requestQueue\",\n      \"resourcePermissions\": [\n        \"READ\",\n        \"WRITE\"\n      ],\n      \"description\": \"queueId from the previous run's CHECKPOINT_META. Needed only for continuation; it stops one checkpoint being used twice.\"\n    },\n    \"maxRunSeconds\": {\n      \"title\": \"Run time bound (seconds)\",\n      \"type\": \"integer\",\n      \"minimum\": 60,\n      \"maximum\": 3600,\n      \"default\": 240,\n      \"description\": \"The run stops itself cleanly before this many seconds and saves a checkpoint.\"\n    },\n    \"feedback\": {\n      \"title\": \"Feedback\",\n      \"type\": \"string\",\n      \"editor\": \"textarea\",\n      \"description\": \"Tell us what you needed and did not get. Read by a human; never changes the output.\"\n    }\n  }\n}",
    "readme": "# Four Square NZ Scraper | $4.00/1K\n\n## What's new, 2026-11-16\n\nBounded examples, explicit costs and integration recipes. NZ pricing is unchanged; no launch price cut applies.\n\n**Recorded run:** `ZxPytWAruAwI84mdb` on 2026-11-15 returned 0 dataset rows; 0 primary events were charged. Status: `SUCCEEDED`. Dataset rows can include free status records.\n\nArchitekture, an independent data studio. architek.earth.\n\nFour Square NZ returns selected-store weekly specials and advertised product prices. Use the daily example to collect repeatable snapshots; use incremental mode only where the input exposes it.\n\n## Tested this week\n\n| Check | Our recorded sample | Field context, 2026-11-16 |\n|---|---|---|\n| Evidence window | 2026-11-15; within the last seven days | Rolling 30-day public counters across 1 title-bucket members |\n| Outcome | SUCCEEDED; 0 dataset rows; 0 charged primary events | 0.00% non-success over 1 runs |\n| Cost | $0.000632 platform cost in the retained run | Not a competitor execution or a matched-input benchmark |\n\nField source: [public Store API](https://api.apify.com/v2/store?search=four%20square). Non-success includes failures, aborts and timeouts. The field total is not a unique-user count. These different workloads do not establish that our actor is more reliable.\n\n## What, data and cost\n\nOne primary `product` event costs **$0.004**; 1,000 cost **$4.00**. Ten primary events plus one collection-delivered cost **$0.19**. Optional events below are additional; status rows are free.\n\n**$5 free credit ≈ 1,212 products** at the primary launch rate after one initial collection-delivered charge. This estimate excludes optional event charges and additional collection starts. Credit pays for billed work; it is separate from the free preview.\n\nSet `preview: true`. One bounded preview returns up to 10 data rows when the source has results. Preview rows are not charged. A preview never silently switches to paid collection.\n\n### Event prices\n\n| Event | USD per event | When charged |\n|---|---:|---|\n| `product` | 0.004 | Delivered primary result |\n| `collection-delivered` | 0.15 | Once per successful collection with delivered rows |\n\nFree and Bronze use the full primary rate; Silver receives 10% off, and Gold, Platinum and Diamond receive 20% off. Secondary event prices do not change. Your run's effective price is shown before collection.\n\nNZ pricing is unchanged; no launch price cut applies.\n\n## Worth knowing up front\n\n- **Specials only.** Four Square has no online product catalogue; foursquare.co.nz publishes each store's weekly specials and promotions, and that is what this actor returns (typically 40 to 60 per store). It cannot return a store's full range or everyday shelf prices.\n- Prices are the in-store specials the site advertises for physical stores. Prices on delivery platforms may differ, as the site itself says.\n- Keyword and department filters are applied to the store's specials list: a keyword keeps specials whose name contains every word.\n- Not returned: barcodes, stock, nutrition or ingredients. `availability` is always `\"unknown\"`.\n- A run stopped by its time bound or spending limit keeps what it delivered and saves `CHECKPOINT`; a run that stops early writes one free status row (`\"recordType\": \"status\"`) that says why.\n\n## Input recipes\n\n### 1. Preview: Milk prices\n\n[Open the configured example task](https://apify.com/architekture/foursquare-nz-scraper/examples/foursquare-nz-basket-compare)\n\n```json\n{\n  \"searchTerms\": [\n    \"milk\"\n  ],\n  \"maxItemsPerQuery\": 1,\n  \"storeId\": \"https://www.foursquare.co.nz/south-island/southland-and-stewart-island/stewart-island\",\n  \"preview\": true,\n  \"continuePreviousRun\": false\n}\n```\n\n### 2. Daily: Milk prices at the selected store\n\n[Open the configured example task](https://apify.com/architekture/foursquare-nz-scraper/examples/foursquare-nz-weekly-tracking)\n\n```json\n{\n  \"searchTerms\": [\n    \"milk\"\n  ],\n  \"maxItemsPerQuery\": 1,\n  \"storeId\": \"https://www.foursquare.co.nz/south-island/southland-and-stewart-island/stewart-island\",\n  \"preview\": false,\n  \"continuePreviousRun\": false\n}\n```\n\n### 3. One-off: Bread prices\n\n[Open the configured example task](https://apify.com/architekture/foursquare-nz-scraper/examples/m058-foursquare-nz-3)\n\n```json\n{\n  \"searchTerms\": [\n    \"bread\"\n  ],\n  \"maxItemsPerQuery\": 1,\n  \"storeId\": \"https://www.foursquare.co.nz/south-island/southland-and-stewart-island/stewart-island\",\n  \"preview\": false,\n  \"continuePreviousRun\": false\n}\n```\n\n### 4. Daily: Butter prices at the selected store\n\n[Open the configured example task](https://apify.com/architekture/foursquare-nz-scraper/examples/m058-foursquare-nz-4)\n\n```json\n{\n  \"searchTerms\": [\n    \"butter\"\n  ],\n  \"maxItemsPerQuery\": 1,\n  \"storeId\": \"https://www.foursquare.co.nz/south-island/southland-and-stewart-island/stewart-island\",\n  \"preview\": false,\n  \"continuePreviousRun\": false\n}\n```\n\n## Recurring collection\n\nCopy the example [Daily: Milk prices at the selected store](https://apify.com/architekture/foursquare-nz-scraper/examples/foursquare-nz-weekly-tracking) into your account. Schedule it in UTC with:\n\n```cron\n0 9 * * *\n```\n\nThe worked ten-result run above repeated daily costs about **$5.70 per 30 days** before optional events and discounts. These tiny recipes demonstrate the input; increase their row limits deliberately. Keep one watch identifier per consistent filter set where incremental mode is available.\n\n## Output and limits\n\nRead the [live input and output definitions](https://api.apify.com/v2/acts/architekture~foursquare-nz-scraper/builds/default). Keep source identifiers, capture time and any status fields when joining snapshots. The data fields remain additive; this listing change does not promise new source data.\n\n## MCP config for Claude and Cursor\n\nClaude: add a custom connector with URL `https://mcp.apify.com?tools=architekture/foursquare-nz-scraper` and complete its sign-in. For Cursor, add this entry to your MCP settings and set your own `APIFY_TOKEN`:\n\n```json\n{\n  \"mcpServers\": {\n    \"foursquare-nz-scraper\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.apify.com?tools=architekture/foursquare-nz-scraper\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${env:APIFY_TOKEN}\"\n      }\n    }\n  }\n}\n```\n\n## n8n and Make\n\n[Python example](https://github.com/architek-earth/examples/blob/main/foursquare-nz-scraper/example.py) and [n8n workflow](https://github.com/architek-earth/examples/blob/main/foursquare-nz-scraper/n8n-workflow.json). In n8n, select a Header Auth credential with header `Authorization` and your bearer token. The workflow is inactive until you choose to run or schedule it.\n\nIn Make, add an HTTP request: `POST https://api.apify.com/v2/acts/architekture~foursquare-nz-scraper/run-sync-get-dataset-items?timeout=120&memory=2048&maxTotalChargeUsd=0.1780000`. Set `Content-Type: application/json`, configure your bearer-token credential, and paste one recipe as the JSON body. Parse the returned array and route status rows separately. Add a scheduler only after inspecting the first result. Do not automatically retry an ambiguous POST; first check whether a run was created.\n\n## FAQ\n\nThe linked public field issues are context for these checks, not claims that the same defects exist in this actor. Grocery examples also use adjacent supermarket issues; tennis uses the adjacent tennis-data field.\n\n### Why can a green run contain no usable rows?\n\nA completed run can still report an empty or blocked source. Read the status rows and run summary before treating it as a successful observation; a missing result is not a measured zero. [Observed field issue](https://apify.com/natanielsantos/sainsbury-s-scraper/issues/VroViV420O4MyZd49).\n\n### Why did I receive fewer rows than the limit?\n\nThe limit is a ceiling, not a guaranteed count. The source may have fewer public matches, filters may remove records, or the run may stop at a time or spending cap. Start with `maxItemsPerQuery`. [Observed field issue](https://apify.com/abotapi/aldi-com-au-scraper/issues/qK7hgyXH1fFverKDS).\n\n### Can this export the whole source?\n\nThe five examples are deliberately bounded. A title or catalogue estimate does not prove full coverage. Use only the collection and continuation modes documented in the input, and retain any partial-run status. [Observed field issue](https://apify.com/abotapi/woolworths-au-scraper/issues/2LGAT6Z7yqnsA055s).\n\n### Which direct identifiers or URLs are accepted?\n\nThis actor uses its documented search/filter inputs. It does not accept an arbitrary source URL as a substitute for those fields. [Observed field issue](https://apify.com/abotapi/woolworths-au-scraper/issues/rCtDTmbxzNwkBd1NG).\n\n### Why is an output field absent?\n\nThe source must publish a value for the actor to return it. Do not infer a missing price, salary, rating, ID or language. Check the output definition and preserve null or absent values in downstream storage. [Observed field issue](https://apify.com/abotapi/aldi-com-au-scraper/issues/oyPyPqccqJOOOEjMc).\n\n### How do I avoid counting a repeated snapshot twice?\n\nTreat each ordinary run as a snapshot. Deduplicate downstream using the source identity and capture time; this listing does not claim cross-run deduplication where the input has no incremental mode. [Observed field issue](https://apify.com/radeance/tesco-scraper/issues/lXsCyyNOEaqkbwfkh).\n\n### What should I check after a source or proxy error?\n\nInspect the run message and the smallest configured example. Do not substitute login cookies or unrelated proxy credentials. A source wall is a coverage limit; preserve partial output and avoid treating failed checks as changes. [Observed field issue](https://apify.com/abotapi/woolworths-au-scraper/issues/oaXKQ0XUiUBA9lnce).\n\n### How do I bound the bill?\n\nSet a run charge cap, for example `$0.178` for these tiny inputs, and keep row limits small. Ten primary results plus one collection/root-post charge cost $0.19 at the listed rate. Optional events and repeated checks add cost. [Observed field issue](https://apify.com/abotapi/woolworths-au-scraper/issues/g4GH2XGeeVDoLS6b5).\n\n### Does the preview switch to paid collection?\n\nSet `preview: true`. One bounded preview returns up to 10 data rows when the source has results. Preview rows are not charged. A preview never silently switches to paid collection. [Observed field issue](https://apify.com/radeance/tesco-scraper/issues/BSJhZqtLwCuQ2lDXW).\n\n### What evidence helps diagnose a changed result?\n\nProvide the run ID, intended country/store/date or filter, and one expected public source URL. Include the status message and missing field name. Never post credentials. The feedback input records a note and does not change output. [Observed field issue](https://apify.com/radeance/tesco-scraper/issues/01bEYMGjje4cAxF1Q).\n\n## For AI agents\n\nCall `architekture/foursquare-nz-scraper` with a bounded recipe and an explicit spending cap. Read the input schema first, request only supported fields, and inspect status rows before summarizing results. Preserve source IDs and capture times. Never interpret absent source data as a confirmed change. Use the same `watchId` for repeat observations only when this actor exposes incremental mode.\n\n**Run health, reviewed 2026-11-16:** last retained run `ZxPytWAruAwI84mdb`, SUCCEEDED, 0 dataset rows, observed 2026-11-15. No new run was started for this listing release.\n\n## More from architek.earth\n\n- [nz price monitor](https://apify.com/architekture/nz-price-monitor)\n- [au price monitor](https://apify.com/architekture/au-price-monitor)\n- [google shopping scraper](https://apify.com/architekture/google-shopping-scraper)\n\n## Support and legal\n\nUse this actor's [issue tab](https://apify.com/architekture/foursquare-nz-scraper/issues) for product questions. Public-source access does not remove your responsibility for permitted use, copyright and privacy. This is an independent product, not an official source API. architek.earth.\n\n## Changelog\n\n- **2026-11-16**: Bounded example tasks, dated health comparison, explicit worked costs, MCP and automation examples, and compatible input-name changes where applicable. NZ pricing is unchanged; no launch price cut applies.\n\n### Earlier releases\n\n- **2026-11-16** : Support approved primary-event Store discount tiers; retain exact event checks and existing preview limits.\n\n- **2026-11-15** : 0.1.2 first public release (runtime identical to canary build 0.1.1; README only).\n",
    "actorDefinition": {
      "actorSpecification": 1,
      "name": "foursquare-nz-scraper",
      "title": "Four Square NZ Scraper | $4.00/1K",
      "description": "Four Square NZ scraper for selected-store weekly specials and advertised product prices. Pay per result. See the pricing table for launch dates, optional charges and preview limits.",
      "version": "0.1",
      "buildTag": "latest",
      "input": {
        "title": "Four Square NZ weekly specials",
        "type": "object",
        "schemaVersion": 1,
        "properties": {
          "storeId": {
            "title": "Store",
            "type": "string",
            "editor": "textfield",
            "description": "A Four Square store page URL, for example https://www.foursquare.co.nz/south-island/southland-and-stewart-island/stewart-island, or its store GUID. Blank selects Four Square Ohope Beach."
          },
          "searchTerms": {
            "title": "Keywords",
            "type": "array",
            "editor": "stringList",
            "default": [],
            "description": "Optional. Keep only specials whose name contains every word of a keyword, for example milk or pams cheese. Each keyword is its own query. Leave empty for all specials."
          },
          "categories": {
            "title": "Departments",
            "type": "array",
            "editor": "stringList",
            "default": [],
            "description": "Optional. Keep only specials in these departments: Beer, Cider & Wine; Chilled & Frozen; Cleaning, Health & Body; Fruit & Vegetables; Meat & Seafood; Pantry & Grocery."
          },
          "maxItemsPerQuery": {
            "title": "Maximum products per query",
            "type": "integer",
            "minimum": 0,
            "maximum": 100000,
            "default": 100,
            "description": "Cap per keyword, department or the all-specials query. 0 means no cap; time and spending limits still apply."
          },
          "preview": {
            "title": "Free preview",
            "type": "boolean",
            "default": true,
            "description": "Free on every run: one page and up to 10 products, never charged. Turn off for paid collection."
          },
          "continuePreviousRun": {
            "title": "Continue previous run",
            "type": "boolean",
            "default": false,
            "description": "Paid only. Picks up from the previous run's saved checkpoint, once."
          },
          "previousStoreId": {
            "title": "Previous run key-value store",
            "type": "string",
            "editor": "resourcePicker",
            "resourceType": "keyValueStore",
            "resourcePermissions": [
              "READ"
            ],
            "description": "The previous run's default key-value store (holds CHECKPOINT and CHECKPOINT_META). Not a supermarket store ID."
          },
          "previousQueueId": {
            "title": "Previous run claim queue",
            "type": "string",
            "editor": "resourcePicker",
            "resourceType": "requestQueue",
            "resourcePermissions": [
              "READ",
              "WRITE"
            ],
            "description": "queueId from the previous run's CHECKPOINT_META. Needed only for continuation; it stops one checkpoint being used twice."
          },
          "maxRunSeconds": {
            "title": "Run time bound (seconds)",
            "type": "integer",
            "minimum": 60,
            "maximum": 3600,
            "default": 240,
            "description": "The run stops itself cleanly before this many seconds and saves a checkpoint."
          },
          "feedback": {
            "title": "Feedback",
            "type": "string",
            "editor": "textarea",
            "description": "Tell us what you needed and did not get. Read by a human; never changes the output."
          }
        }
      },
      "dockerfile": "./Dockerfile",
      "output": {
        "actorOutputSchemaVersion": 1,
        "title": "Products and completion",
        "properties": {
          "results": {
            "type": "string",
            "title": "Products",
            "template": "{{links.apiDefaultDatasetUrl}}/items"
          },
          "summary": {
            "type": "string",
            "title": "Run summary",
            "template": "{{links.apiDefaultKeyValueStoreUrl}}/records/RUN_SUMMARY"
          },
          "checkpoint": {
            "type": "string",
            "title": "Checkpoint",
            "template": "{{links.apiDefaultKeyValueStoreUrl}}/records/CHECKPOINT"
          }
        }
      },
      "storages": {
        "dataset": {
          "actorSpecification": 1,
          "title": "Weekly specials",
          "fields": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Source special ID."
              },
              "name": {
                "type": "string"
              },
              "price": {
                "type": "number",
                "description": "Special price in NZD."
              },
              "priceUnit": {
                "type": "string",
                "description": "ea, kg or pk."
              },
              "pricePerUnit": {
                "type": "number"
              },
              "pricePerUnitLabel": {
                "type": "string"
              },
              "specialType": {
                "type": "string"
              },
              "category": {
                "type": "string"
              },
              "specialEndDate": {
                "type": "string"
              },
              "multibuy": {},
              "purchaseLimit": {
                "type": "string"
              },
              "countryOfOrigin": {
                "type": "string"
              },
              "conditions": {
                "type": "string"
              },
              "imageUrl": {
                "type": "string"
              },
              "chain": {
                "type": "string"
              },
              "storeId": {
                "type": "string"
              },
              "storeName": {
                "type": "string"
              },
              "url": {
                "type": "string"
              },
              "source": {
                "type": "object"
              },
              "availability": {
                "type": "string"
              },
              "recordType": {
                "type": "string"
              },
              "status": {
                "type": "string"
              },
              "failureStage": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          },
          "views": {
            "overview": {
              "title": "Specials",
              "transformation": {
                "fields": [
                  "name",
                  "price",
                  "priceUnit",
                  "pricePerUnit",
                  "pricePerUnitLabel",
                  "category",
                  "specialEndDate",
                  "storeName",
                  "conditions"
                ]
              },
              "display": {
                "component": "table",
                "properties": {
                  "name": {
                    "label": "Product",
                    "format": "text"
                  },
                  "price": {
                    "label": "Price (NZD)",
                    "format": "number"
                  },
                  "priceUnit": {
                    "label": "Per",
                    "format": "text"
                  },
                  "pricePerUnit": {
                    "label": "Unit price",
                    "format": "number"
                  },
                  "pricePerUnitLabel": {
                    "label": "Unit",
                    "format": "text"
                  },
                  "category": {
                    "label": "Department",
                    "format": "text"
                  },
                  "specialEndDate": {
                    "label": "Ends",
                    "format": "text"
                  },
                  "storeName": {
                    "label": "Store",
                    "format": "text"
                  },
                  "conditions": {
                    "label": "Conditions",
                    "format": "text"
                  }
                }
              }
            }
          }
        }
      },
      "readme": "# Four Square NZ Scraper | $4.00/1K\n\n## What's new, 2026-11-16\n\nBounded examples, explicit costs and integration recipes. NZ pricing is unchanged; no launch price cut applies.\n\n**Recorded run:** `ZxPytWAruAwI84mdb` on 2026-11-15 returned 0 dataset rows; 0 primary events were charged. Status: `SUCCEEDED`. Dataset rows can include free status records.\n\nArchitekture, an independent data studio. architek.earth.\n\nFour Square NZ returns selected-store weekly specials and advertised product prices. Use the daily example to collect repeatable snapshots; use incremental mode only where the input exposes it.\n\n## Tested this week\n\n| Check | Our recorded sample | Field context, 2026-11-16 |\n|---|---|---|\n| Evidence window | 2026-11-15; within the last seven days | Rolling 30-day public counters across 1 title-bucket members |\n| Outcome | SUCCEEDED; 0 dataset rows; 0 charged primary events | 0.00% non-success over 1 runs |\n| Cost | $0.000632 platform cost in the retained run | Not a competitor execution or a matched-input benchmark |\n\nField source: [public Store API](https://api.apify.com/v2/store?search=four%20square). Non-success includes failures, aborts and timeouts. The field total is not a unique-user count. These different workloads do not establish that our actor is more reliable.\n\n## What, data and cost\n\nOne primary `product` event costs **$0.004**; 1,000 cost **$4.00**. Ten primary events plus one collection-delivered cost **$0.19**. Optional events below are additional; status rows are free.\n\n**$5 free credit ≈ 1,212 products** at the primary launch rate after one initial collection-delivered charge. This estimate excludes optional event charges and additional collection starts. Credit pays for billed work; it is separate from the free preview.\n\nSet `preview: true`. One bounded preview returns up to 10 data rows when the source has results. Preview rows are not charged. A preview never silently switches to paid collection.\n\n### Event prices\n\n| Event | USD per event | When charged |\n|---|---:|---|\n| `product` | 0.004 | Delivered primary result |\n| `collection-delivered` | 0.15 | Once per successful collection with delivered rows |\n\nFree and Bronze use the full primary rate; Silver receives 10% off, and Gold, Platinum and Diamond receive 20% off. Secondary event prices do not change. Your run's effective price is shown before collection.\n\nNZ pricing is unchanged; no launch price cut applies.\n\n## Worth knowing up front\n\n- **Specials only.** Four Square has no online product catalogue; foursquare.co.nz publishes each store's weekly specials and promotions, and that is what this actor returns (typically 40 to 60 per store). It cannot return a store's full range or everyday shelf prices.\n- Prices are the in-store specials the site advertises for physical stores. Prices on delivery platforms may differ, as the site itself says.\n- Keyword and department filters are applied to the store's specials list: a keyword keeps specials whose name contains every word.\n- Not returned: barcodes, stock, nutrition or ingredients. `availability` is always `\"unknown\"`.\n- A run stopped by its time bound or spending limit keeps what it delivered and saves `CHECKPOINT`; a run that stops early writes one free status row (`\"recordType\": \"status\"`) that says why.\n\n## Input recipes\n\n### 1. Preview: Milk prices\n\n[Open the configured example task](https://apify.com/architekture/foursquare-nz-scraper/examples/foursquare-nz-basket-compare)\n\n```json\n{\n  \"searchTerms\": [\n    \"milk\"\n  ],\n  \"maxItemsPerQuery\": 1,\n  \"storeId\": \"https://www.foursquare.co.nz/south-island/southland-and-stewart-island/stewart-island\",\n  \"preview\": true,\n  \"continuePreviousRun\": false\n}\n```\n\n### 2. Daily: Milk prices at the selected store\n\n[Open the configured example task](https://apify.com/architekture/foursquare-nz-scraper/examples/foursquare-nz-weekly-tracking)\n\n```json\n{\n  \"searchTerms\": [\n    \"milk\"\n  ],\n  \"maxItemsPerQuery\": 1,\n  \"storeId\": \"https://www.foursquare.co.nz/south-island/southland-and-stewart-island/stewart-island\",\n  \"preview\": false,\n  \"continuePreviousRun\": false\n}\n```\n\n### 3. One-off: Bread prices\n\n[Open the configured example task](https://apify.com/architekture/foursquare-nz-scraper/examples/m058-foursquare-nz-3)\n\n```json\n{\n  \"searchTerms\": [\n    \"bread\"\n  ],\n  \"maxItemsPerQuery\": 1,\n  \"storeId\": \"https://www.foursquare.co.nz/south-island/southland-and-stewart-island/stewart-island\",\n  \"preview\": false,\n  \"continuePreviousRun\": false\n}\n```\n\n### 4. Daily: Butter prices at the selected store\n\n[Open the configured example task](https://apify.com/architekture/foursquare-nz-scraper/examples/m058-foursquare-nz-4)\n\n```json\n{\n  \"searchTerms\": [\n    \"butter\"\n  ],\n  \"maxItemsPerQuery\": 1,\n  \"storeId\": \"https://www.foursquare.co.nz/south-island/southland-and-stewart-island/stewart-island\",\n  \"preview\": false,\n  \"continuePreviousRun\": false\n}\n```\n\n## Recurring collection\n\nCopy the example [Daily: Milk prices at the selected store](https://apify.com/architekture/foursquare-nz-scraper/examples/foursquare-nz-weekly-tracking) into your account. Schedule it in UTC with:\n\n```cron\n0 9 * * *\n```\n\nThe worked ten-result run above repeated daily costs about **$5.70 per 30 days** before optional events and discounts. These tiny recipes demonstrate the input; increase their row limits deliberately. Keep one watch identifier per consistent filter set where incremental mode is available.\n\n## Output and limits\n\nRead the [live input and output definitions](https://api.apify.com/v2/acts/architekture~foursquare-nz-scraper/builds/default). Keep source identifiers, capture time and any status fields when joining snapshots. The data fields remain additive; this listing change does not promise new source data.\n\n## MCP config for Claude and Cursor\n\nClaude: add a custom connector with URL `https://mcp.apify.com?tools=architekture/foursquare-nz-scraper` and complete its sign-in. For Cursor, add this entry to your MCP settings and set your own `APIFY_TOKEN`:\n\n```json\n{\n  \"mcpServers\": {\n    \"foursquare-nz-scraper\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.apify.com?tools=architekture/foursquare-nz-scraper\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${env:APIFY_TOKEN}\"\n      }\n    }\n  }\n}\n```\n\n## n8n and Make\n\n[Python example](https://github.com/architek-earth/examples/blob/main/foursquare-nz-scraper/example.py) and [n8n workflow](https://github.com/architek-earth/examples/blob/main/foursquare-nz-scraper/n8n-workflow.json). In n8n, select a Header Auth credential with header `Authorization` and your bearer token. The workflow is inactive until you choose to run or schedule it.\n\nIn Make, add an HTTP request: `POST https://api.apify.com/v2/acts/architekture~foursquare-nz-scraper/run-sync-get-dataset-items?timeout=120&memory=2048&maxTotalChargeUsd=0.1780000`. Set `Content-Type: application/json`, configure your bearer-token credential, and paste one recipe as the JSON body. Parse the returned array and route status rows separately. Add a scheduler only after inspecting the first result. Do not automatically retry an ambiguous POST; first check whether a run was created.\n\n## FAQ\n\nThe linked public field issues are context for these checks, not claims that the same defects exist in this actor. Grocery examples also use adjacent supermarket issues; tennis uses the adjacent tennis-data field.\n\n### Why can a green run contain no usable rows?\n\nA completed run can still report an empty or blocked source. Read the status rows and run summary before treating it as a successful observation; a missing result is not a measured zero. [Observed field issue](https://apify.com/natanielsantos/sainsbury-s-scraper/issues/VroViV420O4MyZd49).\n\n### Why did I receive fewer rows than the limit?\n\nThe limit is a ceiling, not a guaranteed count. The source may have fewer public matches, filters may remove records, or the run may stop at a time or spending cap. Start with `maxItemsPerQuery`. [Observed field issue](https://apify.com/abotapi/aldi-com-au-scraper/issues/qK7hgyXH1fFverKDS).\n\n### Can this export the whole source?\n\nThe five examples are deliberately bounded. A title or catalogue estimate does not prove full coverage. Use only the collection and continuation modes documented in the input, and retain any partial-run status. [Observed field issue](https://apify.com/abotapi/woolworths-au-scraper/issues/2LGAT6Z7yqnsA055s).\n\n### Which direct identifiers or URLs are accepted?\n\nThis actor uses its documented search/filter inputs. It does not accept an arbitrary source URL as a substitute for those fields. [Observed field issue](https://apify.com/abotapi/woolworths-au-scraper/issues/rCtDTmbxzNwkBd1NG).\n\n### Why is an output field absent?\n\nThe source must publish a value for the actor to return it. Do not infer a missing price, salary, rating, ID or language. Check the output definition and preserve null or absent values in downstream storage. [Observed field issue](https://apify.com/abotapi/aldi-com-au-scraper/issues/oyPyPqccqJOOOEjMc).\n\n### How do I avoid counting a repeated snapshot twice?\n\nTreat each ordinary run as a snapshot. Deduplicate downstream using the source identity and capture time; this listing does not claim cross-run deduplication where the input has no incremental mode. [Observed field issue](https://apify.com/radeance/tesco-scraper/issues/lXsCyyNOEaqkbwfkh).\n\n### What should I check after a source or proxy error?\n\nInspect the run message and the smallest configured example. Do not substitute login cookies or unrelated proxy credentials. A source wall is a coverage limit; preserve partial output and avoid treating failed checks as changes. [Observed field issue](https://apify.com/abotapi/woolworths-au-scraper/issues/oaXKQ0XUiUBA9lnce).\n\n### How do I bound the bill?\n\nSet a run charge cap, for example `$0.178` for these tiny inputs, and keep row limits small. Ten primary results plus one collection/root-post charge cost $0.19 at the listed rate. Optional events and repeated checks add cost. [Observed field issue](https://apify.com/abotapi/woolworths-au-scraper/issues/g4GH2XGeeVDoLS6b5).\n\n### Does the preview switch to paid collection?\n\nSet `preview: true`. One bounded preview returns up to 10 data rows when the source has results. Preview rows are not charged. A preview never silently switches to paid collection. [Observed field issue](https://apify.com/radeance/tesco-scraper/issues/BSJhZqtLwCuQ2lDXW).\n\n### What evidence helps diagnose a changed result?\n\nProvide the run ID, intended country/store/date or filter, and one expected public source URL. Include the status message and missing field name. Never post credentials. The feedback input records a note and does not change output. [Observed field issue](https://apify.com/radeance/tesco-scraper/issues/01bEYMGjje4cAxF1Q).\n\n## For AI agents\n\nCall `architekture/foursquare-nz-scraper` with a bounded recipe and an explicit spending cap. Read the input schema first, request only supported fields, and inspect status rows before summarizing results. Preserve source IDs and capture times. Never interpret absent source data as a confirmed change. Use the same `watchId` for repeat observations only when this actor exposes incremental mode.\n\n**Run health, reviewed 2026-11-16:** last retained run `ZxPytWAruAwI84mdb`, SUCCEEDED, 0 dataset rows, observed 2026-11-15. No new run was started for this listing release.\n\n## More from architek.earth\n\n- [nz price monitor](https://apify.com/architekture/nz-price-monitor)\n- [au price monitor](https://apify.com/architekture/au-price-monitor)\n- [google shopping scraper](https://apify.com/architekture/google-shopping-scraper)\n\n## Support and legal\n\nUse this actor's [issue tab](https://apify.com/architekture/foursquare-nz-scraper/issues) for product questions. Public-source access does not remove your responsibility for permitted use, copyright and privacy. This is an independent product, not an official source API. architek.earth.\n\n## Changelog\n\n- **2026-11-16**: Bounded example tasks, dated health comparison, explicit worked costs, MCP and automation examples, and compatible input-name changes where applicable. NZ pricing is unchanged; no launch price cut applies.\n\n### Earlier releases\n\n- **2026-11-16** : Support approved primary-event Store discount tiers; retain exact event checks and existing preview limits.\n\n- **2026-11-15** : 0.1.2 first public release (runtime identical to canary build 0.1.1; README only).\n"
    },
    "buildNumber": "0.1.7",
    "imageDigest": "810d18f1313a5e6431d017ec547127ab97c22a5964bf34be3bd87b20593681c8",
    "actVersion": {
      "sourceType": "SOURCE_FILES",
      "buildTag": "m058-candidate",
      "versionNumber": "0.1"
    },
    "usage": {
      "ACTOR_COMPUTE_UNITS": 0.001968888888888889
    }
  }
}