# Municipal Planning Applications Monitor - Schleswig-Holstein / (`zentrafoundry/municipal-planning-applications-monitor-sh-hh-ni`) Actor

Find contractor lead signals from Hamburg Transparency Portal, Hamburg Planportal, GovData Germany with location, work type, stage, source URL, and confidence.

- **URL**: https://apify.com/zentrafoundry/municipal-planning-applications-monitor-sh-hh-ni.md
- **Developed by:** [Zentra](https://apify.com/zentrafoundry) (community)
- **Categories:** Lead generation, Automation, News
- **Stats:** 2 total users, 1 monthly users, 50.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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

Learn more: https://docs.apify.com/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

## Municipal Planning Applications Monitor - Schleswig-Holstein / Hamburg / Nieders

Find contractor lead signals from Hamburg Transparency Portal, Hamburg Planportal, GovData Germany with location, work type, stage, source URL, and confidence.

### What it does

- Processes configured public sources or user-provided records for focused municipal planning applications - schleswig-holstein / hamburg / niedersachsen monitoring.
- Emits structured rows with source references, stable identifiers, confidence, warnings, and run summary fields.
- Supports sample-mode runs so Apify Store QA and first-time users can inspect output without depending on live third-party availability.

### What it does not do

- Does not scrape private, login-only, paywalled, or access-restricted data unless the user provides approved credentials for a source they control.
- Does not guarantee every field is available from every source; missing or blocked fields are returned as warnings or nulls.
- Does not make legal, financial, compliance, procurement, medical, safety, or regulatory decisions.

### Who this is for

Contractors, suppliers, solar, roofing, HVAC, construction, and local sales teams use this actor when they need focused municipal planning applications - schleswig-holstein / hamburg / niedersachsen output instead of a broad generic scraper or manual checking.

### Buyer outcomes

- Find municipal planning applications - schleswig-holstein / hamburg / niedersachsen project signals earlier than manual planning and permit searches.
- Prioritize outreach with location, work type, permit stage, contractor opportunity, confidence, and source URL.
- Route qualified leads into CRM, sales research, local territory, or partner workflows.

### Sources monitored

- [Hamburg Transparency Portal](https://transparenz.hamburg.de/)
- [Hamburg Planportal](https://geoportal-hamburg.de/planportal/)
- [GovData Germany](https://www.govdata.de/)
- Municipal planning/building portals

### Input

- `sourceMode`: use `sample` for a smoke run or `startUrls` for planning/permit source URLs.
- `startUrls`: public planning authority, permit, renovation, construction, roofing, HVAC, solar, or building-source URLs.
- `sourceIds`: approved planning or municipal source identifiers.
- `maxItems`: bounded number of permit/planning lead signals to return.
- `sinceLastRun`: emit only new or updated planning/permit signals when scheduled.
- `watchlistTerms`: location, work type, building type, contractor trade, or project keywords.
- `webhookUrl`: optional destination for CRM or contractor lead routing.

### How it transforms the input

- Input: public planning authority, building permit, renovation, roofing, HVAC, solar, municipal, or construction source.
- Transformation: identify project type, work type, planning/permit stage, location, and contractor relevance.
- Output: contractor lead with planning authority, project location, work type, stage/status, source URL, opportunity type, and confidence.

### Output

The actor returns planning and permit lead records with authority/source, location, project type, work type, permit stage, contractor opportunity type, source URL, and confidence.

Family-specific fields to expect:

- `permitId`: Permit, planning, or application identifier when available.
- `planningStatus`: Planning, submitted, approved, consultation, or other source status.
- `location`: Project location or municipality.
- `workType`: Roofing, HVAC, solar, renovation, construction, or other work type.
- `projectType`: Building or project category.
- `contractorLeadReason`: Why the record is relevant to a contractor or supplier.
- `sourceUrl`: Public source record URL.

- `recordId`: Stable record ID for exports, dedupe, and downstream joins.
- `title`: Human-readable record title for review and export.
- `sourceName`: Source identifier used to trace where the record came from.
- `sourceUrl`: Direct source URL for review and audit.
- `dedupeKey`: Stable key used for delta mode and duplicate suppression.
- `retrievedAt`: Timestamp showing when the actor retrieved or generated this record.
- `score`: Normalized field for filtering, routing, or downstream review.
- `scoreReasons`: Buyer-readable explanation for the score or match.
- `confidence`: Normalized field for filtering, routing, or downstream review.
- `errors`: Normalized field for filtering, routing, or downstream review.
- `runSummary`: Run-level summary for counts, filters, charges, and next actions.

### Pricing

This actor uses Apify pay-per-event pricing. Current public listing guidance: $29-$49 / 1,000 launch validation records until public data proof is complete. Charges are tied to buyer-visible value events such as `document-parsed`, `dataset-processed`, `record-saved`, `enriched-record`. Small validation runs are supported so you can inspect output before scaling a schedule.

- `document-parsed`: Charge when Municipal Planning Applications Monitor - Schleswig-Holstein / Hamburg / Niedersachsen produces Enriched Record. Typical price: $0.043. A run that produces 10 matching records charges only for the matched buyer-value events and remains capped by the run limit.
- `dataset-processed`: Base charge when Municipal Planning Applications Monitor - Schleswig-Holstein / Hamburg / Niedersachsen writes a non-empty default dataset. Typical price: $0.011. A run that produces 10 matching records charges only for the matched buyer-value events and remains capped by the run limit.
- `record-saved`: Charge for each buyer-visible result saved by Municipal Planning Applications Monitor - Schleswig-Holstein / Hamburg / Niedersachsen. Typical price: $0.003. A run that produces 10 matching records charges only for the matched buyer-value events and remains capped by the run limit.
- `enriched-record`: Charge when Municipal Planning Applications Monitor - Schleswig-Holstein / Hamburg / Niedersachsen adds match scoring, source evidence, or enrichment to a saved result. Typical price: $0.022. A run that produces 10 matching records charges only for the matched buyer-value events and remains capped by the run limit.
- `first-run-cap`: Recommended first run budget cap. Typical price: $3.820. Start with the default small run, inspect the dataset, then raise maxItems or schedule recurring runs.

### API example

```bash
curl -X POST "https://api.apify.com/v2/actors/zentrafoundry~municipal-planning-applications-monitor-sh-hh-ni/runs" \
+  -H "Authorization: Bearer $APIFY_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"maxItems":10,"sourceIds":["HAMBURG-TRANS","HAMBURG-PLAN","GOVDATA-DE"],"includeSourceUrls":true,"includeMatchReasons":true,"outputMode":"buyer-ready-records"}'
````

### Recommended first run

```json
{
    "maxItems": 10,
    "sourceIds": [
        "HAMBURG-TRANS",
        "HAMBURG-PLAN",
        "GOVDATA-DE"
    ],
    "includeSourceUrls": true,
    "includeMatchReasons": true,
    "outputMode": "buyer-ready-records"
}
```

### Sample output

Sample status: `sample_unavailable` at https://zentra.nimblique.studio/external/actor-review/samples/municipal-planning-applications-monitor-sh-hh-ni.json. No fake sample is published; run a bounded real sample refresh before using examples in promotion.

### Recommended public tasks

```json
[
    {
        "name": "Review 10 permit lead signals",
        "description": "Low-cost validation run for checking planning authority, location, work type, and stage fields.",
        "input": {
            "maxItems": 10,
            "sourceIds": [
                "HAMBURG-TRANS",
                "HAMBURG-PLAN",
                "GOVDATA-DE"
            ],
            "includeSourceUrls": true,
            "includeMatchReasons": true,
            "outputMode": "buyer-ready-records",
            "actorSlug": "municipal-planning-applications-monitor-sh-hh-ni"
        }
    },
    {
        "name": "Daily permit lead review",
        "description": "Recurring batch for new planning, building, roofing, HVAC, solar, or renovation leads.",
        "schedule": "Daily during local business hours",
        "input": {
            "maxItems": 25,
            "sourceIds": [
                "HAMBURG-TRANS",
                "HAMBURG-PLAN",
                "GOVDATA-DE"
            ],
            "includeSourceUrls": true,
            "includeMatchReasons": true,
            "outputMode": "buyer-ready-records",
            "actorSlug": "municipal-planning-applications-monitor-sh-hh-ni"
        }
    }
]
```

### Example use cases

- Find municipal planning applications - schleswig-holstein / hamburg / niedersachsen project signals before they become crowded sales opportunities.
- Route qualified permit and planning records into CRM or contractor outreach queues.
- Filter by work type, location, stage, confidence, and source evidence.
- Schedule recurring monitoring for new renovation, HVAC, roofing, solar, or construction leads.

### Trust and compliance

- Uses Hamburg Transparency Portal, Hamburg Planportal, GovData Germany.
- Keeps source URLs and source identifiers in output records for auditability.
- Does not require private credentials unless a source is explicitly configured for approved authenticated access.

### Reliability and QA

- Prefilled Apify Store QA input runs in sample mode and should finish within the automated quality window.
- Empty input is handled with deterministic sample or diagnostic output instead of a crash.
- Demo/sample runs suppress buyer-value charges while still writing representative dataset rows.
- Production runs use bounded `maxItems`, source references, warnings, and run summaries so blocked or changed targets are visible.

### Limitations

- Results depend on public-source availability, source uptime, and source update cadence.
- Public sources can revise records after publication; rerun scheduled tasks for fresh evidence.
- Scores and match reasons are decision-support signals, not legal, financial, procurement, medical, safety, or regulatory advice.
- Large production runs can cost more than the default smoke run; start small, inspect output, then scale schedules.

### Legal and responsible use

Use this Actor only for public data or data you are authorized to process. You are responsible for complying with applicable laws, marketplace terms, robots policies, privacy rules, and source-specific limits.

### Support

Open an issue on the Actor page with the run ID, input summary, expected result, and observed result. Do not include secrets, cookies, auth headers, or private account data.

### FAQ

**Can I run this without URLs?** Yes. The default `sample` mode is designed to succeed without user-supplied URLs, and URL-backed runs can use `startUrls` when needed.

**Can I schedule it?** Yes. Use `sinceLastRun`, `watchlistTerms`, and optional `webhookUrl` to turn the actor into a recurring alert or report workflow.

**How do I verify value before scaling?** Run the recommended first-run input, review the sample output fields, then increase `maxItems` or schedule recurring runs after the dataset matches your use case.

# Actor input Schema

## `sourceMode` (type: `string`):

Choose whether to run the built-in sample or crawl supplied start URLs.

## `mode` (type: `string`):

Use demo for a quick QA-safe sample run, or live to collect real public data.

## `startUrls` (type: `array`):

Approved public source URLs for this Actor run.

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

Upper bound for emitted records and pay-per-event charges.

## `sourceIds` (type: `array`):

Optional source identifiers to include in the run.

## `pricingEvents` (type: `array`):

Buyer-value events expected from this actor.

## `sinceLastRun` (type: `boolean`):

Use Actor state to skip records whose dedupe keys were saved by earlier runs.

## `watchlistTerms` (type: `array`):

Optional buyer terms used to explain matches and recurring monitoring.

## `webhookUrl` (type: `string`):

Optional endpoint that receives a compact completion alert for scheduled runs.

## `includeSourceUrls` (type: `boolean`):

Include source URLs in output records.

## `includeMatchReasons` (type: `boolean`):

Include plain-language match reasons in output records.

## `outputMode` (type: `string`):

Shape of returned records.

## `actorSlug` (type: `string`):

Zentra actor slug used for review and traceability.

## Actor input object example

```json
{
  "sourceMode": "sample",
  "mode": "demo",
  "startUrls": [
    {
      "url": "https://transparenz.hamburg.de/",
      "sourceId": "HAMBURG-TRANS",
      "userData": {
        "sourceId": "HAMBURG-TRANS"
      }
    },
    {
      "url": "https://geoportal-hamburg.de/planportal/",
      "sourceId": "HAMBURG-PLAN",
      "userData": {
        "sourceId": "HAMBURG-PLAN"
      }
    },
    {
      "url": "https://www.govdata.de/",
      "sourceId": "GOVDATA-DE",
      "userData": {
        "sourceId": "GOVDATA-DE"
      }
    }
  ],
  "maxItems": 25,
  "sourceIds": [],
  "pricingEvents": [],
  "sinceLastRun": false,
  "watchlistTerms": [],
  "includeSourceUrls": true,
  "includeMatchReasons": true,
  "outputMode": "sample-records"
}
```

# Actor output Schema

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

No description

# API

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

## JavaScript example

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

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

// Prepare Actor input
const input = {
    "sourceMode": "sample",
    "mode": "demo",
    "startUrls": [
        {
            "url": "https://transparenz.hamburg.de/",
            "sourceId": "HAMBURG-TRANS",
            "userData": {
                "sourceId": "HAMBURG-TRANS"
            }
        },
        {
            "url": "https://geoportal-hamburg.de/planportal/",
            "sourceId": "HAMBURG-PLAN",
            "userData": {
                "sourceId": "HAMBURG-PLAN"
            }
        },
        {
            "url": "https://www.govdata.de/",
            "sourceId": "GOVDATA-DE",
            "userData": {
                "sourceId": "GOVDATA-DE"
            }
        }
    ],
    "maxItems": 25,
    "outputMode": "sample-records"
};

// Run the Actor and wait for it to finish
const run = await client.actor("zentrafoundry/municipal-planning-applications-monitor-sh-hh-ni").call(input);

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

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

```

## Python example

```python
from apify_client import ApifyClient

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

# Prepare the Actor input
run_input = {
    "sourceMode": "sample",
    "mode": "demo",
    "startUrls": [
        {
            "url": "https://transparenz.hamburg.de/",
            "sourceId": "HAMBURG-TRANS",
            "userData": { "sourceId": "HAMBURG-TRANS" },
        },
        {
            "url": "https://geoportal-hamburg.de/planportal/",
            "sourceId": "HAMBURG-PLAN",
            "userData": { "sourceId": "HAMBURG-PLAN" },
        },
        {
            "url": "https://www.govdata.de/",
            "sourceId": "GOVDATA-DE",
            "userData": { "sourceId": "GOVDATA-DE" },
        },
    ],
    "maxItems": 25,
    "outputMode": "sample-records",
}

# Run the Actor and wait for it to finish
run = client.actor("zentrafoundry/municipal-planning-applications-monitor-sh-hh-ni").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 '{
  "sourceMode": "sample",
  "mode": "demo",
  "startUrls": [
    {
      "url": "https://transparenz.hamburg.de/",
      "sourceId": "HAMBURG-TRANS",
      "userData": {
        "sourceId": "HAMBURG-TRANS"
      }
    },
    {
      "url": "https://geoportal-hamburg.de/planportal/",
      "sourceId": "HAMBURG-PLAN",
      "userData": {
        "sourceId": "HAMBURG-PLAN"
      }
    },
    {
      "url": "https://www.govdata.de/",
      "sourceId": "GOVDATA-DE",
      "userData": {
        "sourceId": "GOVDATA-DE"
      }
    }
  ],
  "maxItems": 25,
  "outputMode": "sample-records"
}' |
apify call zentrafoundry/municipal-planning-applications-monitor-sh-hh-ni --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=zentrafoundry/municipal-planning-applications-monitor-sh-hh-ni",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Municipal Planning Applications Monitor - Schleswig-Holstein /",
        "description": "Find contractor lead signals from Hamburg Transparency Portal, Hamburg Planportal, GovData Germany with location, work type, stage, source URL, and confidence.",
        "version": "1.0",
        "x-build-id": "j3STVsDcWlKcVPLXW"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/zentrafoundry~municipal-planning-applications-monitor-sh-hh-ni/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-zentrafoundry-municipal-planning-applications-monitor-sh-hh-ni",
                "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/zentrafoundry~municipal-planning-applications-monitor-sh-hh-ni/runs": {
            "post": {
                "operationId": "runs-sync-zentrafoundry-municipal-planning-applications-monitor-sh-hh-ni",
                "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/zentrafoundry~municipal-planning-applications-monitor-sh-hh-ni/run-sync": {
            "post": {
                "operationId": "run-sync-zentrafoundry-municipal-planning-applications-monitor-sh-hh-ni",
                "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": {
                    "sourceMode": {
                        "title": "Source mode",
                        "enum": [
                            "startUrls",
                            "sample"
                        ],
                        "type": "string",
                        "description": "Choose whether to run the built-in sample or crawl supplied start URLs.",
                        "default": "sample"
                    },
                    "mode": {
                        "title": "Run mode",
                        "enum": [
                            "demo",
                            "live"
                        ],
                        "type": "string",
                        "description": "Use demo for a quick QA-safe sample run, or live to collect real public data.",
                        "default": "live"
                    },
                    "startUrls": {
                        "title": "Start URLs",
                        "type": "array",
                        "description": "Approved public source URLs for this Actor run.",
                        "default": [
                            {
                                "url": "https://transparenz.hamburg.de/",
                                "sourceId": "HAMBURG-TRANS",
                                "userData": {
                                    "sourceId": "HAMBURG-TRANS"
                                }
                            },
                            {
                                "url": "https://geoportal-hamburg.de/planportal/",
                                "sourceId": "HAMBURG-PLAN",
                                "userData": {
                                    "sourceId": "HAMBURG-PLAN"
                                }
                            },
                            {
                                "url": "https://www.govdata.de/",
                                "sourceId": "GOVDATA-DE",
                                "userData": {
                                    "sourceId": "GOVDATA-DE"
                                }
                            }
                        ],
                        "items": {
                            "type": "object",
                            "required": [
                                "url"
                            ],
                            "properties": {
                                "url": {
                                    "type": "string",
                                    "title": "URL of a web page",
                                    "format": "uri"
                                }
                            }
                        }
                    },
                    "maxItems": {
                        "title": "Maximum items",
                        "minimum": 1,
                        "maximum": 1000,
                        "type": "integer",
                        "description": "Upper bound for emitted records and pay-per-event charges.",
                        "default": 1
                    },
                    "sourceIds": {
                        "title": "Source IDs",
                        "type": "array",
                        "description": "Optional source identifiers to include in the run.",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "pricingEvents": {
                        "title": "Pricing events",
                        "type": "array",
                        "description": "Buyer-value events expected from this actor.",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "sinceLastRun": {
                        "title": "Only new records",
                        "type": "boolean",
                        "description": "Use Actor state to skip records whose dedupe keys were saved by earlier runs.",
                        "default": false
                    },
                    "watchlistTerms": {
                        "title": "Watchlist terms",
                        "type": "array",
                        "description": "Optional buyer terms used to explain matches and recurring monitoring.",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "webhookUrl": {
                        "title": "Webhook URL",
                        "type": "string",
                        "description": "Optional endpoint that receives a compact completion alert for scheduled runs."
                    },
                    "includeSourceUrls": {
                        "title": "Include source URLs",
                        "type": "boolean",
                        "description": "Include source URLs in output records.",
                        "default": true
                    },
                    "includeMatchReasons": {
                        "title": "Include match reasons",
                        "type": "boolean",
                        "description": "Include plain-language match reasons in output records.",
                        "default": true
                    },
                    "outputMode": {
                        "title": "Output mode",
                        "enum": [
                            "sample-records",
                            "buyer-ready-records"
                        ],
                        "type": "string",
                        "description": "Shape of returned records.",
                        "default": "sample-records"
                    },
                    "actorSlug": {
                        "title": "Actor slug",
                        "type": "string",
                        "description": "Zentra actor slug used for review and traceability."
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
