# The Knot Wedding Couple and Venue Scraper (`parseforge/theknot-couples-scraper`) Actor Look up couples on The Knot by first and last name and gather their public wedding page. Every record returns both partners names, the wedding date, city and state, the venue name and address when set, and links to the wedding website and registry. Ideal for qualifying leads. - **URL**: https://apify.com/parseforge/theknot-couples-scraper.md - **Developed by:** [ParseForge](https://apify.com/parseforge) (community) - **Categories:** Lead generation, Automation, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $5.43 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ![ParseForge Banner](https://github.com/ParseForge/apify-assets/blob/ad35ccc13ddd068b9d6cba33f323962e39aed5b2/banner.jpg?raw=true) ## ๐Ÿ’ The Knot Wedding Couple Enrichment Scraper > ๐Ÿš€ **Turn a couple's name into their full public wedding profile in seconds.** Input a first and last name, get back both partners, wedding date, city and state, venue, wedding website, and registry, up to 22 fields per record. > ๐Ÿ•’ **Last updated:** 2026-07-08 ยท **๐Ÿ“Š 22 fields** per record ยท public wedding-website data only ยท US, Canada and international couples The Knot Wedding Couple Enrichment Scraper looks up the information a couple has already chosen to publish on their public The Knot wedding website and returns it as clean, structured data. You provide a first name and a last name (for example a guest, vendor, or planner who already knows the couple), and the Actor returns every matching public couple: both partners' names, the wedding date, the city and state, the venue (when the couple added it), the wedding website URL, and the gift registry URL. This is an **enrichment tool, not a discovery or contact-list tool**. It does not browse or dump a directory of strangers. It resolves a name you already have into the public wedding details that The Knot itself displays on its open "Find a Couple" search, then structures them so you can drop them into a spreadsheet or CRM instead of copying by hand. | ๐ŸŽฏ Target Audience | ๐Ÿ’ก Primary Use Cases | |---|---| | Wedding vendors (venues, photographers, planners, florists, caterers) | Confirm a lead's wedding date, location, and venue before quoting | | Registry and gifting services | Match a known couple to their public registry link | | Guests and travel planners | Find a couple's public wedding website and registry from a name | | Wedding-industry analysts | Structure publicly published wedding details for market research | ### ๐Ÿ“‹ What the Actor does 1. Takes a **first name** and **last name** (both required, minimum 2 characters each). 2. Queries The Knot's public "Find a Couple" search (`theknot.com/registry/couplesearch`). 3. Returns every matching public couple with both partners' names, wedding date, city, state, country, wedding website URL, and registry URL. 4. Optionally enriches each result with **venue details** (venue name, address, ceremony and reception locations) by reading the couple's own public wedding-website page. Venue is included only when the couple has filled it in. 5. Optional filters narrow results by **wedding month and year**. ### ๐ŸŽฌ Full Demo (_๐Ÿšง Coming soon_) ### โš™๏ธ Input | Field | Key | Type | Required | Description | |---|---|---|---|---| | Mode | `mode` | select (`search` / `discover`) | No | Default `search`. `search` looks up a name you already have; `discover` browses The Knot's public couple directory with optional filters. | | First Name | `firstName` | string | โœ… Yes (search mode) | First name of one partner (min 2 characters). Applies to search mode. | | Last Name | `lastName` | string | โœ… Yes (search mode) | Last name of one partner (min 2 characters). Applies to search mode. | | Wedding Month | `eventMonth` | string (1-12) | No | Search mode filter. Use together with Wedding Year. | | Wedding Year | `eventYear` | string | No | Search mode filter, for example `2026`. | | Start Couple ID | `startCoupleId` | integer | No | Discover mode only. Optional start point in the public couple space. | | Randomize Start | `randomizeStart` | boolean | No | Discover mode only. Default `true`. Starts from a fresh point so each run sees different public couples. | | US State | `usState` | string (2-letter) | No | Discover mode filter, for example `TX`. | | Wedding Date From | `weddingDateFrom` | string | No | Discover mode filter, `YYYY-MM-DD`. | | Wedding Date To | `weddingDateTo` | string | No | Discover mode filter, `YYYY-MM-DD`. | | Max Scan | `maxScan` | integer | No | Discover mode only. Cap on how many public couple IDs the run walks (your scan budget). | | Include venue details | `includeVenue` | boolean | No | Default `true`. Fetches each couple's public wedding-website page for venue details. Applies to both modes. | | Only complete leads | `onlyComplete` | boolean | No | Default off. When on, keeps only couples that have both partner names, a wedding date, and a city or state; sparse records are skipped and counted in the run log rather than silently dropped. | | Max Items | `maxItems` | integer | No | Free plan: 10. Paid: up to 1,000,000. | **Example 1: basic name lookup with venue enrichment** ```json { "firstName": "Jessica", "lastName": "Miller", "includeVenue": true, "maxItems": 25 } ```` **Example 2: narrow to a specific wedding month and year** ```json { "firstName": "John", "lastName": "Smith", "eventMonth": "6", "eventYear": "2026", "includeVenue": true, "maxItems": 50 } ``` > โš ๏ธ **Good to Know:** The Knot requires **both** a first name and a last name to return results, one for each partner is fine. A name alone can match many couples, so use the month and year filters to narrow down. Venue, address, and ceremony or reception details appear **only when the couple filled them in** on their own public wedding website, so these fields are often blank. That is expected, not an error. ### ๐Ÿ”€ Two modes The Actor runs in one of two modes, set by the `mode` input: - **Search mode** (default): look up a name you already have. Provide `firstName` and `lastName` (optionally `eventMonth` / `eventYear`) and get back the matching public couples. - **Discover mode**: for when you do not have a name yet. It browses The Knot's public couple directory and applies optional filters, `usState` and a `weddingDateFrom` / `weddingDateTo` range, with `maxScan` capping how many public IDs the run walks. It walks the newest public couple IDs downward, so the most recent and upcoming weddings come back first. `onlyComplete` pairs well with discover to drop sparse records. Like search mode, it reads only public pages. ```json {"mode":"discover","usState":"TX","maxScan":5000,"includeVenue":true,"maxItems":500} ``` ### ๐Ÿ“Š Output Each record contains up to 22 fields. Schema: | ๐Ÿท Field | Key | Description | |---|---|---| | ๐Ÿ’‘ Couple | `coupleNames` | Both partners joined, for example "Gregory Gion & Jessica Miller". | | ๐ŸŽ Registry URL | `registryUrl` | Public gift registry link. | | ๐Ÿ”— Wedding Website | `weddingWebsiteUrl` | Public wedding-website URL (when the couple has one). | | ๐Ÿ†” Couple ID | `coupleId` | The Knot's public couple identifier. | | ๐Ÿ‘ค Partner 1 First | `partner1FirstName` | First name of partner one. | | ๐Ÿ‘ค Partner 1 Last | `partner1LastName` | Last name of partner one. | | ๐Ÿ‘ค Partner 2 First | `partner2FirstName` | First name of partner two. | | ๐Ÿ‘ค Partner 2 Last | `partner2LastName` | Last name of partner two. | | ๐Ÿ“… Wedding Date | `weddingDate` | ISO wedding date (blank when the couple hid it). | | ๐Ÿ™ City | `city` | Wedding city. | | ๐Ÿ“ State | `state` | Wedding state or province. | | ๐Ÿ“ฎ ZIP | `zip` | Couple's ZIP / postal code when The Knot exposes it, otherwise null. | | ๐ŸŒŽ Country | `country` | Wedding country. | | ๐Ÿ—บ Location | `location` | Short location label from the search result. | | ๐Ÿ› Venue | `venueName` | Venue name (only when the couple added it). | | ๐Ÿ“ฎ Venue Address | `venueAddress` | Full venue address (only when the couple added it). | | ๐Ÿ™ Venue City | `venueCity` | Venue city. | | ๐Ÿ“ Venue State | `venueState` | Venue state. | | ๐Ÿ’’ Ceremony | `ceremonyVenue` | Ceremony location. | | ๐Ÿฅ‚ Reception | `receptionVenue` | Reception location. | | ๐Ÿ“Œ Wedding Location Text | `weddingLocationText` | "City, ST" label from the wedding website. | | ๐Ÿ’ณ Cash Registry | `hasTransactionalRegistry` | Whether the couple has a cash / transactional registry. | | ๐Ÿ™ˆ Hidden Date | `isHiddenDate` | Whether the couple chose to hide their date. | | ๐Ÿ•’ Scraped At | `scrapedAt` | ISO timestamp of the scrape. | #### Real sample records ```json { "coupleNames": "Gregory Gion & Jessica Miller", "registryUrl": "https://registry.theknot.com/gregory-gion-jessica-miller-april-2025-fl/65174452", "weddingWebsiteUrl": "https://www.theknot.com/gregorygionandjessicamiller", "coupleId": "65174452", "partner1FirstName": "Gregory", "partner1LastName": "Gion", "partner2FirstName": "Jessica", "partner2LastName": "Miller", "weddingDate": "2025-04-05T00:00:00.000Z", "city": "DeLand", "state": "FL", "country": "USA", "location": "FL", "venueName": "Villa Festa", "venueAddress": "518 E. New York Ave., Deland, FL, 32720", "venueCity": "DeLand", "venueState": "FL", "ceremonyVenue": "Villa Festa", "receptionVenue": "Villa Festa", "weddingLocationText": "DeLand, FL", "hasTransactionalRegistry": false, "isHiddenDate": false, "scrapedAt": "2026-07-08T17:29:01.873Z" } ``` ```json { "coupleNames": "Jason Baczek & Jessica Miller", "registryUrl": "https://registry.theknot.com/jason-baczek-jessica-miller-september-2025-co/68709311", "weddingWebsiteUrl": "https://www.theknot.com/jasonbaczekandjessicamiller", "coupleId": "68709311", "partner1FirstName": "Jason", "partner1LastName": "Baczek", "partner2FirstName": "Jessica", "partner2LastName": "Miller", "weddingDate": "2025-09-13T00:00:00.000Z", "city": "Idaho Springs", "state": "CO", "country": "USA", "location": "CO", "venueName": "Blackstone Rivers Ranch", "venueAddress": "3673 Chicago Creek Rd., Idaho Springs, CO, 80452", "venueCity": "Idaho Springs", "venueState": "CO", "ceremonyVenue": "Blackstone Rivers Ranch", "receptionVenue": "Blackstone Rivers Ranch", "weddingLocationText": "Idaho Springs, CO", "hasTransactionalRegistry": true, "isHiddenDate": false, "scrapedAt": "2026-07-08T17:29:02.253Z" } ``` ```json { "coupleNames": "Shane Larocque & Jessica Miller", "registryUrl": "https://registry.theknot.com/shane-larocque-jessica-miller-october-2025-on/71755387", "weddingWebsiteUrl": "https://www.theknot.com/shanelarocqueandjessicamiller", "coupleId": "71755387", "partner1FirstName": "Shane", "partner1LastName": "Larocque", "partner2FirstName": "Jessica", "partner2LastName": "Miller", "weddingDate": "2025-10-03T00:00:00.000Z", "city": "Iroquois", "state": "ON", "country": "CA", "location": "ON", "venueName": null, "venueAddress": null, "venueCity": null, "venueState": null, "ceremonyVenue": null, "receptionVenue": null, "weddingLocationText": null, "hasTransactionalRegistry": false, "isHiddenDate": false, "scrapedAt": "2026-07-08T17:29:02.692Z" } ``` The third record shows the honest reality: a real couple who published a wedding website and registry but did not add venue details, so those fields come back blank. ### โœจ Why choose this Actor - **Name in, structured profile out.** No manual copy-paste from search pages. - **Both partners captured**, not just the person you searched. - **Venue enrichment** reads the couple's own public wedding-website page for venue, address, ceremony, and reception, when they provided them. - **Only public data.** It reads what The Knot already displays publicly, nothing behind a login or passcode. - **Clean exports** to CSV, Excel, JSON, and XML, ready for a CRM or spreadsheet. ### ๐Ÿ“ˆ How it compares to alternatives | Approach | Both partners | Venue | Registry link | Structured export | |---|---|---|---|---| | Manual The Knot search | Partial | Manual | Manual | โŒ | | Generic HTML scraper | โŒ | โŒ | โŒ | Partial | | **This Actor** | โœ… | โœ… (when public) | โœ… | โœ… | ### ๐Ÿš€ How to use 1. **Sign up** for a free Apify account using [this link](https://console.apify.com/sign-up?fpr=vmoqkp). 2. Open the Actor and enter a **first name** and **last name**. 3. (Optional) Add a **wedding month and year** to narrow results, and keep **Include venue details** on. 4. Click **Start** and wait for the run to finish. 5. **Export** your results as CSV, Excel, JSON, or XML from the dataset tab. ### ๐Ÿ’ผ Business use cases | ๐Ÿ› Venue and vendor sales | ๐Ÿ“ธ Photographers and planners | |---|---| | Confirm a lead's wedding date, city, and venue before sending a quote. | Verify event details a prospect gave you against their public page. | | ๐ŸŽ Registry and gifting | ๐Ÿ“Š Market research | |---|---| | Match a known couple to their public registry to send the right gift. | Structure public wedding details to study seasonality and locations. | ### ๐Ÿ”Œ Automating the Actor Run it on a schedule or connect it to your stack with Apify integrations: **Make**, **Zapier**, **Slack**, **Airbyte**, **GitHub**, and **Google Drive**. Push new records straight into a spreadsheet, CRM, or database whenever a run finishes. ### ๐ŸŒŸ Beyond business use cases - **Research:** study how wedding locations and seasons trend across public data. - **Personal:** find a friend's public wedding website and registry from their name. - **Non-profit:** structure publicly shared event details for community outreach. - **Experimentation:** learn structured data extraction from a real public source. ### ๐Ÿค– Ask an AI assistant Paste your exported data into [ChatGPT](https://chat.openai.com), [Claude](https://claude.ai), [Perplexity](https://www.perplexity.ai), or [Microsoft Copilot](https://copilot.microsoft.com) and ask it to summarize venues by region, group couples by month, or draft outreach notes. ### โ“ Frequently Asked Questions **1. What do I need to provide?** A first name and a last name, both at least 2 characters. One name per partner is fine. **2. Can I use it without a name?** Yes, with the optional discover mode. Set `mode` to `discover` and it browses The Knot's public couple directory with optional state and wedding-date filters, no name required. It still reads only public pages, and it does not sell or provide contact data. In the default search mode it works as an enrichment tool that resolves a first and last name you already have. **3. Why is the venue blank for some couples?** Venue, address, and ceremony or reception details appear only when the couple added them to their own public wedding website. Many couples leave them blank. **4. Is any of this private or login-protected data?** No. It reads only what The Knot already shows publicly on its open "Find a Couple" search and public wedding-website pages. Passcode-protected pages are skipped. **5. How many results can one name return?** Common names can match dozens of couples. Use the month and year filters to narrow the set. **6. What date format is used?** Wedding dates are ISO 8601 (for example `2025-09-13T00:00:00.000Z`). **7. Does it work outside the US?** Yes. Results include Canadian and other international couples when The Knot lists them. **8. What export formats are available?** CSV, Excel, JSON, and XML. **9. Are both partners returned?** Yes, both partners' first and last names are captured on every record. **10. How is the free plan limited?** Free runs return up to 10 items. Paid plans support up to 1,000,000. **11. Can I schedule it?** Yes, use Apify Schedules or any of the supported integrations. **12. Is the wedding date always present?** Usually, but a couple can hide their date. When hidden, `weddingDate` is blank and `isHiddenDate` is true. ### ๐Ÿ”Œ Integrate with any app Every run produces a dataset you can pull via the Apify API or push through Make, Zapier, Slack, Airbyte, GitHub, and Google Drive into your own tools. ### ๐Ÿ”— Recommended Actors - Other lead and directory enrichment Actors by ParseForge - Registry and gifting data Actors - Local business and venue data Actors > ๐Ÿ’ก **Pro Tip:** browse the complete [ParseForge collection](https://apify.com/parseforge). **๐Ÿ†˜ Need Help?** [Open our contact form](https://tally.so/r/BzdKgA) > **โš ๏ธ Disclaimer:** This is an independent tool and is not affiliated with, endorsed by, or sponsored by The Knot or The Knot Worldwide. It collects only publicly available data that couples have chosen to publish on their public wedding websites and The Knot's public couple search. Use the data responsibly and in compliance with applicable laws, including privacy and anti-spam regulations. Do not use it to contact individuals who have not consented to be contacted. # Actor input Schema ## `mode` (type: `string`): Search: look up couples by a known first + last name. Discover: collect couples in bulk without any name, by walking public couple IDs. ## `firstName` (type: `string`): Required in Search mode. First name of one partner (min 2 characters). Ignored in Discover mode. ## `lastName` (type: `string`): Required in Search mode. Last name of one partner (min 2 characters). Ignored in Discover mode. ## `eventMonth` (type: `string`): Search mode only. Filter by wedding month. Requires Wedding Year to also be set. ## `eventYear` (type: `string`): Search mode only. Filter by wedding year (for example 2026). Pair with Wedding Month for best results. ## `startCoupleId` (type: `integer`): Discover mode only. Walk public couple IDs downward from this number (newest weddings first). Leave blank to start near the live frontier each run (see Randomize start). The freshest, upcoming weddings sit roughly in the 71,000,000-79,000,000 band. ## `randomizeStart` (type: `boolean`): Discover mode only. When on (default) and no Start Couple ID is given, each run begins at a random point in the populated band so repeated runs return different couples. Ignored if Start Couple ID is set. ## `usState` (type: `string`): Discover mode only. Optional. Keep only couples in this US state. Accepts a 2-letter code (WA) or full name (Washington). Filtered cheaply from the couple's public URL before enrichment. ## `weddingDateFrom` (type: `string`): Discover mode only. Optional. Keep only weddings on or after this date (ISO, e.g. 2025-06-01). Month granularity. ## `weddingDateTo` (type: `string`): Discover mode only. Optional. Keep only weddings on or before this date (ISO, e.g. 2025-12-31). Month granularity. ## `maxScan` (type: `integer`): Discover mode only. Safety budget: the maximum number of couple IDs to probe per run. Prevents a narrow filter from scanning forever. Default 3000. ## `includeVenue` (type: `boolean`): When enabled, fetches each couple's public wedding-website page to capture venue name, address, and ceremony/reception details. Adds one extra request per couple. Passcode-protected sites are skipped (venue left blank). ## `onlyComplete` (type: `boolean`): When enabled, keeps only couples that have both partner names, a public wedding date, and a city or state. Skips sparse records instead of returning them with blank fields. Incomplete couples are counted in the log, not silently dropped. ## `maxItems` (type: `integer`): Free users: Limited to 10 items (preview). Paid users: Optional, max 1,000,000 ## Actor input object example ```json { "mode": "search", "firstName": "Jessica", "lastName": "Miller", "eventMonth": "", "eventYear": "", "randomizeStart": true, "maxScan": 3000, "includeVenue": true, "onlyComplete": false, "maxItems": 10 } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "firstName": "Jessica", "lastName": "Miller", "maxScan": 3000, "maxItems": 10 }; // Run the Actor and wait for it to finish const run = await client.actor("parseforge/theknot-couples-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "firstName": "Jessica", "lastName": "Miller", "maxScan": 3000, "maxItems": 10, } # Run the Actor and wait for it to finish run = client.actor("parseforge/theknot-couples-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "firstName": "Jessica", "lastName": "Miller", "maxScan": 3000, "maxItems": 10 }' | apify call parseforge/theknot-couples-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=parseforge/theknot-couples-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "The Knot Wedding Couple and Venue Scraper", "description": "Look up couples on The Knot by first and last name and gather their public wedding page. Every record returns both partners names, the wedding date, city and state, the venue name and address when set, and links to the wedding website and registry. Ideal for qualifying leads.", "version": "0.1", "x-build-id": "5CKqbjSpWvoJzeLJ2" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/parseforge~theknot-couples-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-parseforge-theknot-couples-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/parseforge~theknot-couples-scraper/runs": { "post": { "operationId": "runs-sync-parseforge-theknot-couples-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/parseforge~theknot-couples-scraper/run-sync": { "post": { "operationId": "run-sync-parseforge-theknot-couples-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "mode": { "title": "Mode", "enum": [ "search", "discover" ], "type": "string", "description": "Search: look up couples by a known first + last name. Discover: collect couples in bulk without any name, by walking public couple IDs.", "default": "search" }, "firstName": { "title": "First Name", "type": "string", "description": "Required in Search mode. First name of one partner (min 2 characters). Ignored in Discover mode." }, "lastName": { "title": "Last Name", "type": "string", "description": "Required in Search mode. Last name of one partner (min 2 characters). Ignored in Discover mode." }, "eventMonth": { "title": "Wedding Month (optional filter)", "enum": [ "", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12" ], "type": "string", "description": "Search mode only. Filter by wedding month. Requires Wedding Year to also be set.", "default": "" }, "eventYear": { "title": "Wedding Year (optional filter)", "type": "string", "description": "Search mode only. Filter by wedding year (for example 2026). Pair with Wedding Month for best results.", "default": "" }, "startCoupleId": { "title": "Start Couple ID (optional)", "minimum": 1, "type": "integer", "description": "Discover mode only. Walk public couple IDs downward from this number (newest weddings first). Leave blank to start near the live frontier each run (see Randomize start). The freshest, upcoming weddings sit roughly in the 71,000,000-79,000,000 band." }, "randomizeStart": { "title": "Randomize start", "type": "boolean", "description": "Discover mode only. When on (default) and no Start Couple ID is given, each run begins at a random point in the populated band so repeated runs return different couples. Ignored if Start Couple ID is set.", "default": true }, "usState": { "title": "US State filter", "type": "string", "description": "Discover mode only. Optional. Keep only couples in this US state. Accepts a 2-letter code (WA) or full name (Washington). Filtered cheaply from the couple's public URL before enrichment." }, "weddingDateFrom": { "title": "Wedding date from", "type": "string", "description": "Discover mode only. Optional. Keep only weddings on or after this date (ISO, e.g. 2025-06-01). Month granularity." }, "weddingDateTo": { "title": "Wedding date to", "type": "string", "description": "Discover mode only. Optional. Keep only weddings on or before this date (ISO, e.g. 2025-12-31). Month granularity." }, "maxScan": { "title": "Max IDs to scan", "minimum": 1, "maximum": 5000000, "type": "integer", "description": "Discover mode only. Safety budget: the maximum number of couple IDs to probe per run. Prevents a narrow filter from scanning forever. Default 3000." }, "includeVenue": { "title": "Include venue details", "type": "boolean", "description": "When enabled, fetches each couple's public wedding-website page to capture venue name, address, and ceremony/reception details. Adds one extra request per couple. Passcode-protected sites are skipped (venue left blank).", "default": true }, "onlyComplete": { "title": "Only complete leads", "type": "boolean", "description": "When enabled, keeps only couples that have both partner names, a public wedding date, and a city or state. Skips sparse records instead of returning them with blank fields. Incomplete couples are counted in the log, not silently dropped.", "default": false }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 1000000, "type": "integer", "description": "Free users: Limited to 10 items (preview). Paid users: Optional, max 1,000,000" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```