Python SDK

The Geonode Scraper Python SDK wraps every public Scraper API endpoint. This guide:

API overview: what each API group does and when to use it
Shared request options: enums used across APIs (formats, processing_mode, proxy, wait)
Each API section: that API’s methods, request fields, then code + live response per method

Responses below are from live runs against https://scraper.geonode.io.

Setup

pip install geonode-scraper-sdk python-dotenv

Create a .env file:

GEONODE_SCRAPER_API_KEY=your_geonode_key
SCRAPER_API_BASE_URL=https://scraper.geonode.io

import os
from dotenv import load_dotenv
from geonode_scraper_sdk import Configuration, ApiClient

load_dotenv()

configuration = Configuration(
    host=os.environ.get("SCRAPER_API_BASE_URL", "https://scraper.geonode.io"),
    api_key={"ApiKeyAuth": os.environ["GEONODE_SCRAPER_API_KEY"]},
)

Host

Use https://scraper.geonode.io for production. If host is omitted, the client defaults to http://localhost.

API overview

API	SDK class	Endpoint	When to use
Extract	`ExtractionApi`	`/v1/extract`	One URL → HTML/Markdown. Sync or async.
Batch	`BatchApi`	`/v1/batch`	Many known URLs in one job.
Crawl	`CrawlApi`	`/v1/crawl`	Seed URL + follow links (depth/limit).
Map	`MapApi`	`/v1/map`	Discover URLs without scraping content.
Search	`SearchApi`	`/v1/search`	Web search → ranked URLs.
Usage	`UsageApi`	`/v1/usage`	Live concurrency vs plan limit.
Statistics	`StatisticsApi`	`/v1/statistics`	Historical counts, tokens, success rate.
System	`SystemApi`	`/health`	Service health check.
Webhooks	`WebhooksApi`	`/v1/webhooks`	Callbacks when async jobs finish.

Typical flows: single page → Extract sync · known URL list → Batch · whole site → Map then Crawl/Batch · discovery → Search then Extract · production async → ASYNC + Webhooks.

Each API section below lists that API’s methods and request fields, then walks every method with code and a live response.

Shared request options

Enums and helpers reused by Extract, Batch, and Crawl. Per-API field tables live in each API section.

Output formats

from geonode_scraper_sdk import OutputFormat

# Available values:
OutputFormat.HTML       # "html": raw page HTML
OutputFormat.MARKDOWN   # "markdown": cleaned Markdown

Pass as a list: formats=[OutputFormat.MARKDOWN] or [OutputFormat.HTML, OutputFormat.MARKDOWN]. Extract defaults to [HTML]; Batch/Crawl default to server-side defaults if omitted.

Processing mode (Extract only)

from geonode_scraper_sdk import ProcessingMode

ProcessingMode.SYNC    # "sync": block until content is ready (default)
ProcessingMode.ASYNC   # "async": return job_id immediately; poll get_job_result

Batch, Crawl, Map, and Search are always async jobs (create → poll status / get job).

Proxy settings

from geonode_scraper_sdk import ProxySettings, ProxyType

ProxySettings(
    country="US",                    # ISO 3166-1 alpha-2 (optional)
    type=ProxyType.RESIDENTIAL,      # residential | datacenter | mix
)

Wait config (JS rendering)

Used with render_js=True to control headless browser timing:

from geonode_scraper_sdk import WaitConfig, WaitUntil

WaitConfig(
    wait_until=WaitUntil.NETWORKIDLE,  # commit | domcontentloaded | load | networkidle
    wait_for="#content",               # CSS selector (optional)
    wait_timeout=10000,                # ms, 0-30000
)

Custom headers

Pass a dict on Extract/Batch requests: headers={"User-Agent": "my-bot/1.0"}.

Job status values

Async jobs move through: queued → processing → completed | failed | cancelled.

Extraction API

ExtractionApi (/v1/extract)

Methods:

extract_v1_extract_post(extract_request): sync or async extract
get_job_result_v1_extract_job_id_get(job_id): fetch async job result
list_jobs_v1_extract_jobs_get(...): paginate past extract jobs

ExtractRequest fields:

Field	Type	Notes
`url`	`str`	Required. Target URL.
`formats`	`[OutputFormat]`	Default `[HTML]`.
`processing_mode`	`ProcessingMode`	`SYNC` (default) or `ASYNC`.
`render_js`	`bool`	Headless browser. Default `False`.
`proxy`	`ProxySettings`	Optional.
`headers`	`dict[str, str]`	Optional request headers.
`wait_config`	`WaitConfig`	Optional browser wait policy.

extract_v1_extract_post (sync)

Scrape one URL and return content in the same response.

from geonode_scraper_sdk import (
    ApiClient,
    ExtractRequest,
    ExtractionApi,
    OutputFormat,
    ProcessingMode,
)

with ApiClient(configuration) as api_client:
    api = ExtractionApi(api_client)

    response = api.extract_v1_extract_post(
        ExtractRequest(
            url="https://docs.geonode.com/docs/scraper-api/quick-start",
            formats=[OutputFormat.MARKDOWN],
            processing_mode=ProcessingMode.SYNC,
        )
    )

    markdown = response.data.markdown if response.data else ""
    print("Scraped content length:", len(markdown or ""))
    print("Tokens charged:", response.tokens_charged)
    print("Preview:", (markdown or "")[:300])

Response (live run):

Scraped content length: 15871
Tokens charged: 1
Preview: ---
canonical: https://docs.geonode.com/docs/scraper-api/quick-start
meta-description: Get your API key, authenticate requests, and choose the right API for your use case.
...

extract_v1_extract_post (async)

Submit a job and receive a job_id immediately. Poll with get_job_result_v1_extract_job_id_get.

import time
from geonode_scraper_sdk import (
    ApiClient,
    ExtractRequest,
    ExtractionApi,
    OutputFormat,
    ProcessingMode,
)

with ApiClient(configuration) as api_client:
    api = ExtractionApi(api_client)

    submit = api.extract_v1_extract_post(
        ExtractRequest(
            url="https://docs.geonode.com/docs/scraper-api/quick-start",
            formats=[OutputFormat.MARKDOWN],
            processing_mode=ProcessingMode.ASYNC,
        )
    )
    print("Job ID:", submit.job_id)

    while True:
        job = api.get_job_result_v1_extract_job_id_get(str(submit.job_id))
        print("Status:", job.status)
        if str(job.status).lower().endswith("completed"):
            if job.data and job.data.markdown:
                print("Scraped content length:", len(job.data.markdown))
            break
        time.sleep(2)

Response (live run):

Job ID: 6d92b4d5-c9c2-4b66-aa0a-98c07c3a31da
Status: queued
Status: completed
Scraped content length: 15871

get_job_result_v1_extract_job_id_get

Fetch status and content for a single extract job (used after async submit or to re-read a past job).

from geonode_scraper_sdk import ApiClient, ExtractionApi

JOB_ID = "6d92b4d5-c9c2-4b66-aa0a-98c07c3a31da"

with ApiClient(configuration) as api_client:
    api = ExtractionApi(api_client)
    job = api.get_job_result_v1_extract_job_id_get(JOB_ID)

    md_len = len(job.data.markdown) if job.data and job.data.markdown else 0
    print("Job ID:", JOB_ID)
    print("Status:", job.status)
    print("Markdown length:", md_len)

Response (live run):

Job ID: 6d92b4d5-c9c2-4b66-aa0a-98c07c3a31da
Status: JobStatus.COMPLETED
Markdown length: 15871

list_jobs_v1_extract_jobs_get

Paginate past extract jobs. Optional filters: status, start_date, end_date, page, page_size.

from geonode_scraper_sdk import ApiClient, ExtractionApi

with ApiClient(configuration) as api_client:
    api = ExtractionApi(api_client)
    page = api.list_jobs_v1_extract_jobs_get(page=1, page_size=3)

    jobs = getattr(page, "items", None) or getattr(page, "jobs", None) or []
    for job in jobs:
        print(job.job_id, job.status)

Response (live run):

752b8599-5915-441c-bc1f-b9fb0d938f72 JobStatus.COMPLETED
0bcd424e-b5ab-4b85-9cbd-5b44f7ed433c JobStatus.COMPLETED
0706f42e-d9fd-4076-bfae-3cb365f4b634 JobStatus.COMPLETED

extract_v1_extract_post (JS + proxy)

Same method with render_js, residential proxy, and wait config for dynamic pages.

from geonode_scraper_sdk import (
    ApiClient,
    ExtractRequest,
    ExtractionApi,
    OutputFormat,
    ProcessingMode,
    ProxySettings,
    ProxyType,
    WaitConfig,
    WaitUntil,
)

with ApiClient(configuration) as api_client:
    api = ExtractionApi(api_client)

    response = api.extract_v1_extract_post(
        ExtractRequest(
            url="https://example.com",
            formats=[OutputFormat.MARKDOWN],
            processing_mode=ProcessingMode.SYNC,
            render_js=True,
            proxy=ProxySettings(country="US", type=ProxyType.RESIDENTIAL),
            wait_config=WaitConfig(
                wait_until=WaitUntil.NETWORKIDLE,
                wait_timeout=10000,
            ),
        )
    )

    markdown = response.data.markdown if response.data else ""
    print("Scraped content length:", len(markdown or ""))
    print("Tokens charged:", response.tokens_charged)
    print("Preview:", (markdown or "")[:250])

Response (live run):

Scraped content length: 250
Tokens charged: 1
Preview: ---
meta-viewport: width=device-width, initial-scale=1
title: Example Domain
---

# Example Domain

This domain is for use in documentation examples without needing permission. Avoid use in operations.

[Learn more](https://iana.org/domains/example)

Batch API

BatchApi (/v1/batch)

Methods:

create_batch_v1_batch_post(batch_request): submit URLs as one job
get_batch_status_v1_batch_job_id_get(job_id, page, page_size): poll status / results
list_batch_jobs_v1_batch_jobs_get(...): list past batch jobs
cancel_batch_v1_batch_job_id_delete(job_id): cancel a running batch

BatchRequest fields:

Field	Type	Notes
`urls`	`[str]`	Required. 1-1000 URLs.
`formats`	`[OutputFormat]`	Optional.
`render_js`	`bool`	Apply to every URL.
`proxy`	`ProxySettings`	Optional.
`headers`	`dict[str, str]`	Optional.
`wait_config`	`WaitConfig`	Optional.
`ignore_invalid_urls`	`bool`	Default `True`. Skip bad URLs instead of failing.

create_batch_v1_batch_post

Submit many URLs as one batch job.

from geonode_scraper_sdk import ApiClient, BatchApi, BatchRequest, OutputFormat

with ApiClient(configuration) as api_client:
    api = BatchApi(api_client)

    accepted = api.create_batch_v1_batch_post(
        BatchRequest(
            urls=[
                "https://docs.geonode.com/docs/scraper-api/quick-start",
                "https://docs.geonode.com/docs/scraper-api",
            ],
            formats=[OutputFormat.MARKDOWN],
        )
    )
    print("Batch job:", accepted.job_id)
    print("Accepted URLs:", accepted.accepted_urls)

Response (live run):

Batch job: 863e95fa-24c0-4638-aa09-a70235fdade1
Accepted URLs: 2

get_batch_status_v1_batch_job_id_get

Poll progress and read per-URL results (paginated with page, page_size).

import time
from geonode_scraper_sdk import ApiClient, BatchApi, BatchRequest, OutputFormat

with ApiClient(configuration) as api_client:
    api = BatchApi(api_client)

    accepted = api.create_batch_v1_batch_post(
        BatchRequest(
            urls=["https://docs.geonode.com/docs/scraper-api/quick-start"],
            formats=[OutputFormat.MARKDOWN],
        )
    )

    while True:
        status = api.get_batch_status_v1_batch_job_id_get(
            job_id=accepted.job_id, page=1, page_size=10
        )
        print(
            status.status,
            status.completed_urls,
            "/",
            status.total_urls,
        )
        if str(status.status).lower().endswith("completed"):
            break
        time.sleep(3)

Response (live run):

queued 0 / 1
processing 0 / 1
completed 1 / 1

list_batch_jobs_v1_batch_jobs_get

List batch jobs with optional status, start_date, end_date, pagination.

from geonode_scraper_sdk import ApiClient, BatchApi

with ApiClient(configuration) as api_client:
    api = BatchApi(api_client)
    page = api.list_batch_jobs_v1_batch_jobs_get(page=1, page_size=3)

    for job in (page.jobs or [])[:3]:
        print(job.job_id, job.status, job.completed_urls, "/", job.accepted_urls)

Response (live run):

1255853d-eef7-45c4-9abe-7e3863535584 JobStatus.COMPLETED 1 / 1
863e95fa-24c0-4638-aa09-a70235fdade1 JobStatus.COMPLETED 2 / 2
d403ad87-66ce-4a48-823b-21e8ebbfb899 JobStatus.COMPLETED 2 / 2

cancel_batch_v1_batch_job_id_delete

Stop scheduling new batch items. In-flight extractions drain.

from geonode_scraper_sdk import ApiClient, BatchApi, BatchRequest, OutputFormat

with ApiClient(configuration) as api_client:
    api = BatchApi(api_client)

    accepted = api.create_batch_v1_batch_post(
        BatchRequest(
            urls=["https://docs.geonode.com/docs/scraper-api/quick-start"],
            formats=[OutputFormat.MARKDOWN],
        )
    )
    cancelled = api.cancel_batch_v1_batch_job_id_delete(accepted.job_id)
    print("Cancelled:", cancelled.job_id, cancelled.status)

Response (live run):

Cancelled: 883bd4ad-cb9c-49bc-99f5-d007fce5a217 JobStatus.CANCELLED

Crawl API

CrawlApi (/v1/crawl)

Methods:

create_crawl_v1_crawl_post(crawl_request): start crawl from seed URL
get_crawl_status_v1_crawl_job_id_get(job_id, page, page_size): poll status / pages
list_crawl_jobs_v1_crawl_jobs_get(...): list past crawl jobs
cancel_crawl_v1_crawl_job_id_delete(job_id): cancel a running crawl

CrawlRequest fields:

Field	Type	Notes
`url`	`str`	Required seed URL.
`depth`	`int`	BFS depth, 1-10. Default `2`.
`limit`	`int`	Max pages, 1-10000. Default `50`.
`same_domain_only`	`bool`	Default `True`.
`include_subdomains`	`bool`	Default `False`.
`formats`	`[OutputFormat]`	Optional per-page formats.
`render_js`	`bool`	Optional.
`proxy`	`ProxySettings`	Optional.
`wait_config`	`WaitConfig`	Optional.

create_crawl_v1_crawl_post

Start a crawl from a seed URL.

from geonode_scraper_sdk import ApiClient, CrawlApi, CrawlRequest, OutputFormat

with ApiClient(configuration) as api_client:
    api = CrawlApi(api_client)

    accepted = api.create_crawl_v1_crawl_post(
        CrawlRequest(
            url="https://docs.geonode.com/docs/scraper-api",
            depth=2,
            limit=5,
            formats=[OutputFormat.MARKDOWN],
            same_domain_only=True,
        )
    )
    print("Crawl job:", accepted.job_id)
    print("Estimated pages:", accepted.estimated_pages)

Response (live run):

Crawl job: efd86d85-f843-4b71-ad58-d5fec23a0ec3
Estimated pages: 5

get_crawl_status_v1_crawl_job_id_get

Poll crawl progress and read scraped pages (paginated).

import time
from geonode_scraper_sdk import ApiClient, CrawlApi, CrawlRequest, OutputFormat

with ApiClient(configuration) as api_client:
    api = CrawlApi(api_client)

    accepted = api.create_crawl_v1_crawl_post(
        CrawlRequest(
            url="https://docs.geonode.com/docs/scraper-api",
            depth=2,
            limit=5,
            formats=[OutputFormat.MARKDOWN],
            same_domain_only=True,
        )
    )

    while True:
        status = api.get_crawl_status_v1_crawl_job_id_get(
            job_id=accepted.job_id, page=1, page_size=10
        )
        print(
            status.status,
            status.completed_pages,
            "/",
            status.total_pages,
        )
        if str(status.status).lower().endswith("completed"):
            break
        time.sleep(4)

Response (live run):

queued 0 / 5
processing 0 / 5
...
completed 5 / 5

list_crawl_jobs_v1_crawl_jobs_get

List crawl jobs. Optional filters: url, status, start_date, end_date.

from geonode_scraper_sdk import ApiClient, CrawlApi

with ApiClient(configuration) as api_client:
    api = CrawlApi(api_client)
    page = api.list_crawl_jobs_v1_crawl_jobs_get(page=1, page_size=2)

    for job in (page.jobs or [])[:2]:
        print(job.job_id, job.status, job.completed_pages, "/", job.total_pages)

Response (live run):

34ebec40-5353-4933-ac11-6be09b85c448 JobStatus.COMPLETED 1 / 1
efd86d85-f843-4b71-ad58-d5fec23a0ec3 JobStatus.COMPLETED 5 / 5

cancel_crawl_v1_crawl_job_id_delete

Cancel a queued or processing crawl.

from geonode_scraper_sdk import ApiClient, CrawlApi, CrawlRequest, OutputFormat

with ApiClient(configuration) as api_client:
    api = CrawlApi(api_client)

    accepted = api.create_crawl_v1_crawl_post(
        CrawlRequest(
            url="https://docs.geonode.com/docs/scraper-api",
            depth=1,
            limit=50,
            formats=[OutputFormat.MARKDOWN],
        )
    )
    cancelled = api.cancel_crawl_v1_crawl_job_id_delete(accepted.job_id)
    print("Cancelled:", cancelled.job_id, cancelled.status)

Response (live run):

Cancelled: d8e5dec2-7450-4023-8fba-858243ac5339 JobStatus.CANCELLED

Map API

MapApi (/v1/map)

Methods:

map_urls_v1_map_post(map_request): discover URLs under a base URL
list_map_jobs_v1_map_jobs_get(...): list past map jobs
get_map_job_v1_map_job_id_get(job_id): fetch a completed map job

MapRequest fields:

Field	Type	Notes
`url`	`str`	Required base URL.
`include_subdomains`	`bool`	Widen discovery scope. Default `False`.
`ignore_query_parameters`	`bool`	Normalize URLs. Default `True`.
`search`	`str`	Optional path/url filter.

map_urls_v1_map_post

Discover URLs synchronously (returns links inline). Large sites may also create a persisted map job you can fetch later.

from geonode_scraper_sdk import ApiClient, MapApi, MapRequest

with ApiClient(configuration) as api_client:
    api = MapApi(api_client)

    result = api.map_urls_v1_map_post(
        MapRequest(url="https://docs.geonode.com/docs/scraper-api")
    )

    print("Link count:", len(result.links or []))
    for link in (result.links or [])[:5]:
        print(link.source, link.url)

Response (live run):

Link count: 112
sitemap https://docs.geonode.com/docs/scraper-api
sitemap https://docs.geonode.com/docs/scraper-api/quick-start
sitemap https://docs.geonode.com/docs/scraper-api/additional-resources/choosing_scraper_api_plan
sitemap https://docs.geonode.com/docs/scraper-api/additional-resources/faq
sitemap https://docs.geonode.com/docs/scraper-api/additional-resources/pricing-and-requests

list_map_jobs_v1_map_jobs_get

List past map jobs. Optional filters: url, status, start_date, end_date.

from geonode_scraper_sdk import ApiClient, MapApi

with ApiClient(configuration) as api_client:
    api = MapApi(api_client)
    page = api.list_map_jobs_v1_map_jobs_get(page=1, page_size=2)

    for job in (page.jobs or [])[:2]:
        print(job.job_id, job.status, job.url)

Response (live run):

b38bdc1c-2b53-4ccb-8947-6673cf5b53e0 JobStatus.COMPLETED https://docs.geonode.com/docs/scraper-api
bc074160-7d94-4a74-bb77-1e4f96f9c5cb JobStatus.COMPLETED https://docs.geonode.com/docs/scraper-api

get_map_job_v1_map_job_id_get

Retrieve full link list for a completed map job.

from geonode_scraper_sdk import ApiClient, MapApi

JOB_ID = "b38bdc1c-2b53-4ccb-8947-6673cf5b53e0"

with ApiClient(configuration) as api_client:
    api = MapApi(api_client)
    detail = api.get_map_job_v1_map_job_id_get(JOB_ID)

    links = detail.links or []
    print("Job ID:", JOB_ID)
    print("Link count:", len(links))
    for link in links[:3]:
        print(link.source, link.url)

Response (live run):

Job ID: b38bdc1c-2b53-4ccb-8947-6673cf5b53e0
Link count: 112
sitemap https://docs.geonode.com/docs/scraper-api
sitemap https://docs.geonode.com/docs/scraper-api/quick-start
sitemap https://docs.geonode.com/docs/scraper-api/additional-resources/choosing_scraper_api_plan

Search API

SearchApi (/v1/search)

Methods:

search_v1_search_post(search_request): run a search query
list_search_jobs_v1_search_jobs_get(...): list past search jobs
get_search_job_v1_search_job_id_get(job_id): fetch a completed search job

SearchRequest fields:

Field	Type	Notes
`query`	`str`	Required search string.
`page`	`int`	Result page 1-20. Default `1`.
`safe`	`str`	`off` \| `moderate` \| `strict`. Default `off`.
`time_range`	`str`	Optional: `day`, `week`, `month`, `year`.
`locale`	`str`	Optional locale hint.

search_v1_search_post

Run a search query. Returns results inline and a job_id for later lookup.

from geonode_scraper_sdk import ApiClient, SearchApi, SearchRequest

with ApiClient(configuration) as api_client:
    api = SearchApi(api_client)

    result = api.search_v1_search_post(
        SearchRequest(query="geonode scraper api")
    )

    print("Job ID:", result.job_id)
    print("Hit count:", len(result.results or []))
    for hit in (result.results or [])[:5]:
        print(hit.position, hit.title, hit.url)

Response (live run):

Job ID: 6aef3e93-f714-4eb5-ab7a-c0b00fee5dea
Hit count: 15
1 Wholesale proxies & web data infrastructure | Geonode https://geonode.com/
2 Geonode - PyPI https://pypi.org/user/Geonode/
3 pavel.s - PyPI https://pypi.org/user/pavel.s/
4 Geonode Documentation | Geonode https://docs.geonode.com/
5 GeoNode https://geonode.org/

list_search_jobs_v1_search_jobs_get

List past search jobs. Optional filters: query, status, start_date, end_date.

from geonode_scraper_sdk import ApiClient, SearchApi

with ApiClient(configuration) as api_client:
    api = SearchApi(api_client)
    page = api.list_search_jobs_v1_search_jobs_get(page=1, page_size=2)

    for job in (page.jobs or [])[:2]:
        print(job.job_id, job.query, job.status)

Response (live run):

6aef3e93-f714-4eb5-ab7a-c0b00fee5dea geonode scraper api JobStatus.COMPLETED
0a0375f1-a36a-4c51-929d-5fa4b2425877 geonode scraper api JobStatus.COMPLETED

get_search_job_v1_search_job_id_get

Re-fetch full results for a search job.

from geonode_scraper_sdk import ApiClient, SearchApi

JOB_ID = "6aef3e93-f714-4eb5-ab7a-c0b00fee5dea"

with ApiClient(configuration) as api_client:
    api = SearchApi(api_client)
    detail = api.get_search_job_v1_search_job_id_get(JOB_ID)

    hits = detail.results or []
    print("Job ID:", JOB_ID)
    print("Hit count:", len(hits))
    for hit in hits[:3]:
        print(hit.position, hit.title, hit.url)

Response (live run):

Job ID: 6aef3e93-f714-4eb5-ab7a-c0b00fee5dea
Hit count: 15
1 Wholesale proxies & web data infrastructure | Geonode https://geonode.com/
2 Geonode - PyPI https://pypi.org/user/Geonode/
3 pavel.s - PyPI https://pypi.org/user/pavel.s/

Usage API

UsageApi (/v1/usage)

Methods:

get_concurrency_usage_v1_usage_concurrency_get(): live concurrency in use vs plan limit

get_concurrency_usage_v1_usage_concurrency_get

Check live work-concurrency slots against your plan limit.

from geonode_scraper_sdk import ApiClient, UsageApi

with ApiClient(configuration) as api_client:
    api = UsageApi(api_client)
    usage = api.get_concurrency_usage_v1_usage_concurrency_get()
    print(usage.work_concurrency_in_use, usage.work_concurrency_limit)

Response (live run):

0 50

Statistics API

StatisticsApi (/v1/statistics)

Methods:

get_statistics_v1_statistics_get(...): extraction counts, tokens, success rate

get_statistics_v1_statistics_get

Historical extraction counts, token usage, success rate.

from geonode_scraper_sdk import ApiClient, StatisticsApi

with ApiClient(configuration) as api_client:
    api = StatisticsApi(api_client)
    stats = api.get_statistics_v1_statistics_get()

    print("Extraction count:", stats.extraction_count)
    print("Success rate:", stats.success_rate)
    print("Recent token days:", len(stats.tokens_used or []))

Response (live run):

Extraction count: 4378
Success rate: 0.95112
Recent token days: 7

System API

SystemApi (/health)

Methods:

health_check_health_get(): service health check

health_check_health_get

Confirm the Scraper API is up.

from geonode_scraper_sdk import ApiClient, SystemApi

with ApiClient(configuration) as api_client:
    api = SystemApi(api_client)
    health = api.health_check_health_get()
    print(health.service, health.status, health.version)

Response (live run):

Scraper API HealthStatus.OK 0.1.0

Webhooks API

WebhooksApi (/v1/webhooks)

Event types: extract_completed, batch_completed, crawl_completed.

Methods:

create_webhook_v1_webhooks_post(webhook_create): register a webhook
list_webhooks_v1_webhooks_get(...): list webhooks
get_webhook_v1_webhooks_webhook_id_get(webhook_id): get one webhook
update_webhook_v1_webhooks_webhook_id_patch(webhook_id, webhook_update): update
delete_webhook_v1_webhooks_webhook_id_delete(webhook_id): delete
list_deliveries_v1_webhooks_webhook_id_deliveries_get(...): delivery history
rotate_secret_v1_webhooks_webhook_id_rotate_secret_post(webhook_id): rotate signing secret

WebhookCreate fields:

Field	Type	Notes
`url`	`str`	Required callback URL.
`event_type`	`WebhookEventType`	`extract_completed`, `batch_completed`, or `crawl_completed`.
`description`	`str`	Optional label.

create_webhook_v1_webhooks_post

from geonode_scraper_sdk import (
    ApiClient,
    WebhookCreate,
    WebhookEventType,
    WebhooksApi,
)

with ApiClient(configuration) as api_client:
    api = WebhooksApi(api_client)

    created = api.create_webhook_v1_webhooks_post(
        WebhookCreate(
            url="https://example.com/webhook",
            event_type=WebhookEventType.EXTRACT_COMPLETED,
            description="sdk guide demo",
        )
    )
    print("Created:", created.id, created.url, created.event_type)

Response (live run):

Created: b9ea9375-90a0-47cb-bb37-48c4c0804925 https://example.com/webhook WebhookEventType.EXTRACT_COMPLETED

list_webhooks_v1_webhooks_get

from geonode_scraper_sdk import ApiClient, WebhooksApi

with ApiClient(configuration) as api_client:
    api = WebhooksApi(api_client)
    page = api.list_webhooks_v1_webhooks_get(page=1, page_size=5)

    items = getattr(page, "items", None) or []
    print("Webhook count:", len(items))
    for wh in items:
        print(wh.id, wh.url, wh.event_type)

Response (live run):

Webhook count: 0

get_webhook_v1_webhooks_webhook_id_get

from geonode_scraper_sdk import ApiClient, WebhooksApi

WEBHOOK_ID = "b9ea9375-90a0-47cb-bb37-48c4c0804925"

with ApiClient(configuration) as api_client:
    api = WebhooksApi(api_client)
    wh = api.get_webhook_v1_webhooks_webhook_id_get(WEBHOOK_ID)
    print(wh.url, wh.event_type, wh.is_active)

Response (live run):

https://example.com/webhook WebhookEventType.EXTRACT_COMPLETED True

update_webhook_v1_webhooks_webhook_id_patch

from geonode_scraper_sdk import ApiClient, WebhookUpdate, WebhooksApi

WEBHOOK_ID = "b9ea9375-90a0-47cb-bb37-48c4c0804925"

with ApiClient(configuration) as api_client:
    api = WebhooksApi(api_client)
    updated = api.update_webhook_v1_webhooks_webhook_id_patch(
        WEBHOOK_ID,
        WebhookUpdate(description="updated by sdk guide"),
    )
    print("Description:", updated.description)

Response (live run):

Description: updated by sdk guide

rotate_secret_v1_webhooks_webhook_id_rotate_secret_post

from geonode_scraper_sdk import ApiClient, WebhooksApi

WEBHOOK_ID = "b9ea9375-90a0-47cb-bb37-48c4c0804925"

with ApiClient(configuration) as api_client:
    api = WebhooksApi(api_client)
    rotated = api.rotate_secret_v1_webhooks_webhook_id_rotate_secret_post(WEBHOOK_ID)
    print("New secret length:", len(rotated.secret or ""))

Response (live run):

New secret length: 64

list_deliveries_v1_webhooks_webhook_id_deliveries_get

from geonode_scraper_sdk import ApiClient, WebhooksApi

WEBHOOK_ID = "b9ea9375-90a0-47cb-bb37-48c4c0804925"

with ApiClient(configuration) as api_client:
    api = WebhooksApi(api_client)
    page = api.list_deliveries_v1_webhooks_webhook_id_deliveries_get(
        WEBHOOK_ID, page=1, page_size=5
    )
    items = getattr(page, "items", None) or []
    print("Delivery count:", len(items))

Response (live run):

Delivery count: 0

delete_webhook_v1_webhooks_webhook_id_delete

from geonode_scraper_sdk import ApiClient, WebhooksApi

WEBHOOK_ID = "b9ea9375-90a0-47cb-bb37-48c4c0804925"

with ApiClient(configuration) as api_client:
    api = WebhooksApi(api_client)
    api.delete_webhook_v1_webhooks_webhook_id_delete(WEBHOOK_ID)
    print("Deleted:", WEBHOOK_ID)

Response (live run):

Deleted: b9ea9375-90a0-47cb-bb37-48c4c0804925

Error handling

Non-2xx HTTP responses raise ApiException with status, body, and parsed data. Invalid models can fail before the HTTP call (Pydantic ValidationError).

Validation error (empty URL):

from geonode_scraper_sdk import ApiClient, ExtractRequest, ExtractionApi

with ApiClient(configuration) as api_client:
    api = ExtractionApi(api_client)
    try:
        api.extract_v1_extract_post(ExtractRequest(url=""))
    except Exception as exc:
        print(type(exc).__name__, exc)

Response (live run):

ValidationError 1 validation error for ExtractRequest
url
  String should have at least 1 character [type=string_too_short, input_value='', input_type=str]

API error (fake job ID):

from geonode_scraper_sdk import ApiClient, ApiException, ExtractionApi

with ApiClient(configuration) as api_client:
    api = ExtractionApi(api_client)
    try:
        api.get_job_result_v1_extract_job_id_get(
            "00000000-0000-0000-0000-000000000000"
        )
    except ApiException as exc:
        print(exc.status)
        print(exc.body)

Response (live run):

404
{"code":"NOT_FOUND","message":"Job 00000000-0000-0000-0000-000000000000 not found","correlation_id":"f430c05f-5aea-4e98-bcf2-34fabb743f8c","retryable":false,"details":null}

For package versions and *_with_http_info() variants, see geonode-scraper-sdk on PyPI.

Python SDK

On this page