# Sitemap URL Extractor - Links, Lastmod & Nested Indexes (`kestrel/sitemap-url-extractor`) Actor

Extract sitemap URLs from XML or gzip files and nested indexes. One row per URL: link, lastmod, priority, frequency and source sitemap. Filter URL paths and dates; exclude known IDs for repeat runs. Source parsing is billed even with zero matches. No browser or proxy.

- **URL**: https://apify.com/kestrel/sitemap-url-extractor.md
- **Developed by:** [Tedj MEABIOU](https://apify.com/kestrel) (community)
- **Categories:** Developer tools, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.10 / 1,000 url rows

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Sitemap URL Extractor - Links, Lastmod & Nested Indexes

Extract sitemap URLs and lastmod values from public XML documents, gzip files and nested indexes. Each delivered record identifies a page and the file that listed it, giving downstream workflows an auditable inventory for content discovery, SEO analysis or crawl preparation. No browser, proxy subscription or third-party API key is needed.

### Connect this Actor to your AI agent

[Open the MCP setup and small sample call](https://mtedj.github.io/kestrel-actors-examples/agents/sitemap-url-extractor/) for this Actor, or [choose a related toolkit](https://mtedj.github.io/kestrel-actors-examples/agents/) for a larger workflow. The setup includes the input schema and current pricing events.

For a per-run dollar ceiling, use the hosted MCP `call-actor` tool with `callOptions.maxTotalChargeUsd` outside the Actor input. After the run finishes, retrieve the dataset with `get-dataset-items`; a run response is not the data itself. Check the live schema and pricing before a large or recurring run.

### Sitemap inputs: which request maps to which JSON?

Use this actor when you already know a site's published XML source address. It follows child indexes and produces deduplicated page records. It does not discover source addresses from homepages, crawl page content, verify page availability, or prove that a page is indexed by a search engine.

| Request | Input |
| --- | --- |
| First three Python documentation links | `{"sitemapUrls":["https://docs.python.org/sitemap.xml"],"maxResults":3}` |
| Product pages from a supplied source | `{"sitemapUrls":["https://example.com/sitemap.xml"],"urlContains":["/products/"],"maxResults":100}` |
| Recently declared changes | `{"sitemapUrls":["https://example.com/sitemap.xml"],"sinceDate":"2026-10-01"}` |
| Exclude previously delivered records | Pass earlier `id` values in `excludeIds` |

The example.com addresses illustrate input structure; replace them with a real source. The Python documentation example is a live source.

### URLs: how do I run a small first extraction?

```json
{"sitemapUrls":["https://docs.python.org/sitemap.xml"],"maxResults":3,"maxSources":2}
```

Supply 1–50 exact public source addresses in `sitemapUrls`. Duplicate inputs are processed once. `maxResults` defaults to 1,000 delivered records and accepts values up to 100,000. The global output cap applies after filtering and duplicate removal. If the source has fewer qualifying records, the actor returns fewer; a cap is a maximum rather than a promise of availability.

### Lastmod: what do the fields mean?

The dataset contains one `type="url"` record per unique page address. `url` is the declared location. `id` is a deterministic SHA-256 identifier derived from that location. `lastmod`, `changefreq` and `priority` preserve the publisher's values as strings or null. `sitemap_url` identifies the file supplying the record, and `fetched_at` records retrieval time in UTC.

These are publisher declarations, not measurements of actual page changes or search ranking. An omitted date stays null. A recent retrieval time does not establish that the page itself was recently modified. Duplicate page addresses across child files are delivered once; the first encountered record supplies the metadata.

```json
{"type":"url","id":"example-id","url":"https://example.com/products/a","lastmod":"2026-10-29","changefreq":null,"priority":"0.8","sitemap_url":"https://example.com/sitemap.xml","fetched_at":"2026-10-30T00:00:00+00:00"}
```

This row is illustrative. The source determines the actual metadata and timestamps.

### Filtering: how do dates and exclusions work?

`urlContains` defaults to an empty list, which keeps all addresses. Values such as `["/products/","/blog/"]` are literal, case-insensitive substring matches combined with OR. They are not regular expressions. Different filter fields combine with AND.

`sinceDate` defaults to an empty string. A supplied ISO date or timestamp is an inclusive UTC lower bound on the declared modification time. When a cutoff is present, missing or invalid modification dates are excluded. Without a cutoff those records remain eligible.

`excludeIds` accepts identifiers from earlier datasets. No monitoring state is automatically retained between runs. Your workflow must save identifiers and send them back on the next execution. Unchanged addresses remain the same identifier even if their metadata changes, so omit ID exclusion when your purpose is to inspect updated metadata for existing pages.

### Pricing: what does an empty run cost?

A successfully parsed file costs **$0.005**, including an index document. Each delivered page costs an additional **$0.0001**, or **$0.10 per 1,000 records**. One file yielding 1,000 records therefore costs **$0.105**. An index plus two child files yielding 1,000 unique records costs **$0.115**.

An empty valid file, or a valid file whose entries are all filtered or excluded, still incurs the parsing fee. This pays for the source check. Malformed XML, blocked requests, unsupported documents, duplicate sources and invalid input do not incur a parsing event. Filtered and duplicate records do not incur a URL event. There is no startup fee; compute and transfer are included in event prices.

Set `maxTotalChargeUsd` as an **Apify run option**, not an input property. The actor checks the remaining event allowance before requesting another source and before charging a page. A parsed file can consume the remaining allowance without leaving enough for a page; that file's parsing remains a completed billable operation. Already completed events remain charged when a later request fails.

### Limits: how much source data can be processed?

`maxSources` defaults to 30 and accepts 1–100 unique source attempts. Index files and failed attempts count against this operational cap, while only successful parses count toward the source fee. Children are traversed breadth first and repeated addresses are skipped, preventing index loops. Processing stops when either source, result or spending limits are reached.

Each download has an 8 MB decompressed limit, including gzip expansion, and a bounded request timeout. This is deliberately below the protocol's maximum file size. Split larger sources into smaller documents before using this actor. Redirects are bounded and every destination must be public HTTP or HTTPS on a standard port. Private network destinations and embedded credentials are rejected. XML DTDs and external entities are unsupported.

### API and workflow integrations

Use the Apify Console, schedules, API, n8n, Make or an MCP client. Scheduling is configured in Apify; this actor does not create schedules itself. Start with a small result cap and inspect the output before increasing it.

Python:

```python
import os
from apify_client import ApifyClient
client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("kestrel/sitemap-url-extractor").call(
    run_input={"sitemapUrls": ["https://docs.python.org/sitemap.xml"], "maxResults": 3},
    max_total_charge_usd=0.10,
)
print(list(client.dataset(run["defaultDatasetId"]).iterate_items()))
```

JavaScript:

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('kestrel/sitemap-url-extractor').call(
  { sitemapUrls: ['https://docs.python.org/sitemap.xml'], maxResults: 3 },
  { maxTotalChargeUsd: 0.10 }
);
console.log((await client.dataset(run.defaultDatasetId).listItems()).items);
```

curl:

```bash
curl 'https://api.apify.com/v2/acts/kestrel~sitemap-url-extractor/run-sync-get-dataset-items?maxTotalChargeUsd=0.10' \
  -H "Authorization: Bearer $APIFY_TOKEN" -H 'Content-Type: application/json' \
  -d '{"sitemapUrls":["https://docs.python.org/sitemap.xml"],"maxResults":3}'
```

### FAQ: how are errors and partial results reported?

Read the `SUMMARY` record in the default key-value store for row counts, attempted and parsed sources, exclusions, errors and the stop reason. Operational errors are kept there rather than inserted into the page dataset. A run in which every attempted source fails ends as failed. Mixed success preserves the valid records and lists the unsuccessful sources. A cap or an empty valid document is not a source failure.

#### Can this discover every page on a website?

No. It extracts only addresses the supplied documents declare, within the configured bounds. Publishers can omit pages, and files can be stale. Use an additional crawler if you need link discovery or page content.

#### Does it fetch the listed pages?

No. Only source files and their child indexes are fetched. Listed locations are output records, not crawl requests.

#### Are there legal or access requirements?

Use public sources you are authorized to access and comply with applicable source terms and laws. Public availability does not grant an unrestricted right to republish content. The actor does not log in, solve challenges or retrieve private network resources.

Last verified working: 2026-10-30. See the changelog for tested release behavior.

# Changelog

This Actor's version history is a separate document: https://apify.com/kestrel/sitemap-url-extractor/changelog.md

# Actor input Schema

## `sitemapUrls` (type: `array`):

Pass 1–50 public sitemap URLs, e.g. \['https://docs.python.org/sitemap.xml']. Exact source URLs only; no website discovery. XML must be at most 8 MB decompressed. Successfully parsed sources are billed even when filters leave zero rows.

## `maxResults` (type: `integer`):

1000 for URLs or 100 for entries by default. Caps delivered rows across all sources after filters. Reaching this cap stops further source requests.

## `sinceDate` (type: `string`):

Empty (default) keeps every date. Example: "2026-10-01" or "2026-10-01T12:00:00Z". Inclusive UTC cutoff on lastmod or publication date (updated date when publication is absent). Rows with missing or invalid dates are excluded when set. Source parsing is still billed.

## `urlContains` (type: `array`):

\[] (default) keeps all URLs. Example: \["/products/", "/blog/"] keeps URLs containing either literal substring, case insensitive. Filters apply before the result cap and URL billing; source parsing remains billed.

## `maxSources` (type: `integer`):

30 (default), including index files, malformed responses and failed requests. Example: 5 limits processing to five unique source URLs. Nested indexes are followed breadth first; loops and repeated sources are skipped. Source fees apply only to successfully parsed files.

## `excludeIds` (type: `array`):

\[] (default) keeps all unseen rows within this run. Pass id values from an earlier dataset, e.g. \["previous-id"], to omit them. No state is remembered automatically. Source parsing remains billed even when every row is excluded.

## Actor input object example

```json
{
  "sitemapUrls": [
    "https://docs.python.org/sitemap.xml"
  ],
  "maxResults": 1000,
  "sinceDate": "",
  "urlContains": [],
  "maxSources": 30,
  "excludeIds": []
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `summary` (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 = {
    "sitemapUrls": [
        "https://docs.python.org/sitemap.xml"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("kestrel/sitemap-url-extractor").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 = { "sitemapUrls": ["https://docs.python.org/sitemap.xml"] }

# Run the Actor and wait for it to finish
run = client.actor("kestrel/sitemap-url-extractor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "sitemapUrls": [
    "https://docs.python.org/sitemap.xml"
  ]
}' |
apify call kestrel/sitemap-url-extractor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kestrel/sitemap-url-extractor"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/VP4Z40JMUErY2accE/builds/8ScIs7tfGeQUSCRX0/openapi.json
