Poland Court Judgments API – SAOS Case Law

Poland court judgments API: search orzeczenia sądów through the public SAOS API. Export case numbers (sygnatury), courts, judges, dates, keywords, search snippets, and optional published full text (pełny tekst orzeczenia) for legal research, legal-tech tools, and retrieval augmented generation. SAOS coverage is incomplete and varies by court. This Actor searches the available index; it is not an exhaustive bulk archive or database synchronisation service. Polski opis: orzeczenia sądów z publicznego API SAOS — sygnatury, sądy, sędziowie, hasła i opcjonalnie pełny tekst; eksport CSV, JSON lub Excel.

What data can you get

Every row contains the SAOS ID, case numbers, court and judgment types, original judgment date, a date-validity flag, court name and code when available, division when present, judges with special roles, keywords, plain search snippet, canonical source links, and UTC scrape time. Search snippets are excerpts, not full text.

With includeFullText, rows also contain text, original formatted textLength, textTruncated, legal bases, compact referenced regulations and cases, judgment result, means of appeal, summary, decision, source judgment URL, publication date, and textError. Missing optional values are null or empty lists. A detail failure retains the metadata and records a bounded error in textError.

Full-text runs default to onlyWithText: true. The Actor skips candidates whose search snippet is empty after HTML removal and whitespace cleanup, before any detail request, dataset row, or judgment charge. Metadata runs keep these candidates by default. Set onlyWithText: false to include them, or set it to true to filter metadata runs too. A nonempty snippet is a heuristic, not a guarantee of usable full text. Detail failures still produce metadata with textError.

The structured output excludes source.publisher, source.reviser, and courtReporters. Judges remain in the output. Published snippets and full text may themselves mention court staff. The Actor preserves that published text apart from HTML formatting and the requested character cap, preserves anonymisation markers, and does not attempt deanonymisation.

How to use

1. Choose a court or keep ANY to search all available courts.
2. Set a date range or a phrase. Use double quotes inside phrase for an exact SAOS phrase.
3. Set maxItems and choose whether to retrieve full text.
4. Run the Actor and export the dataset as JSON, CSV, or Excel through Apify.

{
  "courtType": "COMMON",
  "dateFrom": "2026-01-01",
  "phrase": "\"kredyt frankowy\"",
  "includeFullText": true,
  "onlyWithText": true,
  "maxItems": 10
}

The examples directory contains four small inputs. The "last week" example has a fixed range, 2026-10-12 through 2026-10-18; change those dates for later runs.

Input

CHF loan cases in common courts from 2026, with published full text:

{
  "courtType": "COMMON",
  "dateFrom": "2026-01-01",
  "phrase": "\"kredyt frankowy\"",
  "includeFullText": true,
  "onlyWithText": true,
  "maxItems": 10
}

Supreme Court judgments in a historical window (metadata + full text when available):

{
  "courtType": "SUPREME",
  "dateFrom": "2015-01-01",
  "dateTo": "2016-06-30",
  "includeFullText": true,
  "onlyWithText": true,
  "maxItems": 10
}

Field	Default	Meaning
courtType	ANY	ANY, COMMON, SUPREME, ADMINISTRATIVE, CONSTITUTIONAL_TRIBUNAL, or NATIONAL_APPEAL_CHAMBER. Coverage differs.
commonCourtType	empty	APPEAL, REGIONAL, or DISTRICT. Requires COMMON; maps to API ccCourtType.
dateFrom, dateTo	empty	Inclusive judgment dates in YYYY-MM-DD; start cannot follow end.
phrase	empty	SAOS query language, sent as all; quotes request an exact phrase.
keywords	[]	Repeated keywords combine with AND. SAOS provides keywords for common courts.
judgmentTypes	[]	OR across DECISION, RESOLUTION, SENTENCE, REGULATION, REASONS.
includeFullText	false	Fetch details for accepted candidates.
onlyWithText	includeFullText	Skip candidates with empty normalized search snippets. Defaults to true for full text and false for metadata. Explicit false disables the filter.
textFormat	plain	plain preserves paragraph breaks; html preserves source HTML.
maxTextChars	0	Cap full text after formatting; zero means unlimited. Capped HTML can contain incomplete markup.
sortOrder	newest	newest or oldest, by judgment date.
skipInvalidDates	true	Skip malformed dates, years outside 1900–2100, and dates after the UTC scrape date.
maxItems	100	Actual delivered row cap, 1–100000. Skips do not consume this cap.
onlyNew	false	Skip previously delivered IDs in persistent named storage.
stateKey	default	1–100 letters, digits, underscores, or hyphens. Independent feeds need separate keys.
maxRequestsPerSecond	1	Shared request-start cap, 0.2–3, including retries. At most two requests in flight; timeout 120 seconds.

onlyNew retains the most recent 50,000 delivered IDs. It detects new IDs, not updates to existing judgments. Runs that share a stateKey must not overlap, because concurrent saves can overwrite each other's state. A crash before this history is saved can cause a repeat in a separate run. Search results can also change during pagination; the source provides no snapshot guarantee.

Resuming the same run restores delivered IDs and counts regardless of onlyNew, including rows saved after the last checkpoint. The run keeps its original maxItems cap and does not deliver or charge those IDs again. This progress belongs to the current run; onlyNew controls ID history across separate runs.

Text filtering may require more search pages to fill maxItems. Skipped candidates do not count toward that limit or enter the seen-ID store. The run can finish below maxItems when the available results are exhausted.

Output

This shortened example shows the metadata fields. Full-text runs add the fields described above.

{
  "id": 551102,
  "caseNumbers": ["I C 1055/23"],
  "courtType": "COMMON",
  "judgmentType": "SENTENCE",
  "judgmentDate": "2026-09-01",
  "judgmentDateValid": true,
  "courtName": "Sąd Okręgowy w Warszawie",
  "courtCode": "15450500",
  "divisionName": "I Wydział Cywilny",
  "judges": [{"name": "Andrzej Kuryłek", "specialRoles": ["PRESIDING_JUDGE"]}],
  "keywords": ["kredyt indeksowany do waluty obcej"],
  "textSnippet": "Sygnatura akt I C 1055/23 ...",
  "urlSaos": "https://www.saos.org.pl/judgments/551102",
  "urlApi": "https://www.saos.org.pl/api/judgments/551102",
  "scrapedAt": "2026-10-18T12:00:00+00:00"
}

Search metadata remains authoritative when details differ. textLength counts characters after the selected formatting and before truncation. textError is null on success. On detail errors, text is null, textLength is zero, and the row uses the metadata event. Search outages fail the run after retries while preserving delivered rows and final statistics. A repeated search page is retried once; another repeated page fails the run with a source error and preserves delivered rows.

Pricing (pay per event)

Event	USD per delivered row	When charged
judgment	$0.003	Metadata, including a failed full-text request.
judgment-with-text	$0.010	Successfully retrieved full text, including requested truncation.

Each delivered row selects exactly one of these events. Seen IDs, rejected dates, candidates excluded by onlyWithText, and records refused by the SDK budget do not produce a row or one of these charges. A nonempty snippet followed by a detail failure still produces a judgment charge. The Actor honours ACTOR_MAX_TOTAL_CHARGE_USD through the SDK and stops when no further item is admitted. The last admitted row still counts even when its receipt reports that the budget has been reached. The Actor never manually charges apify-* events.

.actor/pay_per_event.json documents the event configuration to enter in the Apify Console when publishing. The platform does not activate prices from that file automatically. Platform charges, if applicable, follow your Apify plan and configured pricing.

Use cases

• Legal-tech search and case law analysis by court, date, and subject.
• Compliance monitoring with schedules and persistent new-ID tracking.
• AI agents and RAG systems with published full text and source links.
• Research datasets scoped to a specific question and available source coverage.

FAQ

Is there an API for Polish court judgments / SAOS / orzeczenia sądów? Yes. SAOS exposes a public search and detail API. This Actor turns live orzeczenia sądów into a filterable table (court, date, phrase, keywords, optional full text) callable from the Apify API, with CSV/JSON/Excel export.

How do I export SAOS judgments to CSV or Excel? Set courtType, a date range or phrase, maxItems, optionally includeFullText, run the Actor, then download the dataset as CSV or Excel from the run page or via the Apify API.

Does it include the full judgment text? Only when you set includeFullText: true. Full-text runs default to onlyWithText: true, which skips candidates with an empty search snippet before any detail request. Metadata-only runs stay cheaper (judgment event).

What is the difference vs scraping saos.org.pl or the bulk download API? This Actor uses the official SAOS search/detail HTTP API (not HTML scraping). For a complete archive or continuous synchronisation, evaluate the source's dedicated bulk download API instead — this Actor searches the available index for scoped queries.

How fresh is the data?

Recorded public API checks on 2026-10-18 found about 474,000 COMMON judgments, including 2026. The newest SUPREME results were from June 2016, Constitutional Tribunal results from December 2015, and KIO results from September 2018. ADMINISTRATIVE returned no results. These are observations of SAOS, not promises about future coverage. ANY includes those historical collections; selecting a recent range can return no rows for those courts.

Some published dates are malformed or in the future. The default skipInvalidDates excludes them without charging. Set it to false to inspect the original date alongside judgmentDateValid: false.

Where does the data come from?

The Actor uses SAOS /api/search/judgments and /api/judgments/{id}. It does not scrape private systems. See the SAOS search API documentation and single-object API documentation. For a complete archive or synchronisation, evaluate the source's dedicated bulk download API instead.

Why can full-text runs be slower or return metadata with an error?

In a user-provided observation recorded on 2026-10-18, both modes processed the same 100 COMMON judgments dated 2026-09-01 through 2026-10-15. Metadata used 1 request and took 33 seconds. Full-text retrieval with the snippet prefilter disabled used 101 requests and took 137 seconds, with 0 retries. Of those 100 detail responses, 60 had empty textContent, comprising 43 REASONS, 11 SENTENCE, and 6 REGULATION records. Exactly those 60 records also had empty search snippets. The historical run delivered them with textError and charged the judgment event.

These observations describe one sample and the behavior before default snippet filtering. They do not predict runtime, missing-text rates, or savings for other queries. The current default skips empty snippets before detail retrieval in full-text mode. It may fetch more search pages to fill maxItems. A nonempty snippet can still lead to missing full text or a failed detail request. Text availability and source coverage vary by court and date.

Can I reuse the data?

The source publishes court judgments. Check the source's current terms, applicable reuse rules, and your obligations for the intended use. This Actor does not provide legal advice or remove source anonymisation.

How does the Actor protect the public API?

The default is one request per second across search, details, and retries. The configurable maximum is three. Timeouts, transport failures, 429, selected server errors, and invalid JSON maintenance pages use bounded exponential backoff with full jitter and numeric Retry-After. Other client errors fail immediately. A failed detail request degrades to metadata; a failed search ends the run with a clear status.

Integrations

Run the Actor through the Apify API, schedules, or the Console. Use Apify webhooks to trigger downstream work after a run. Read the dataset through the API or connect it to an MCP client or AI agent using your Apify integration. The Actor itself does not send emails, configure webhooks, or require external account credentials.

Development

Use Python 3.13. Install dependencies in your development environment, then run locally with the Apify CLI. Local execution uses storage/ and does not require an Apify login.

pip install -r requirements-dev.txt
rm -rf -- ./storage
apify run --input-file examples/smoke-5.json
python -m pytest -q

Remove ./storage before each local run to discard previous input, output, and simulated charging state. For simulated pay-per-event billing, load the ready-made pricing JSON and explicitly initialise both event counts to zero. SDK 4.1 ignores an empty {} count map, which prevents it from loading the local pricing configuration. Unknown events then receive a local testing fallback price of USD 1. The pricing JSON also sets the SDK's automatic default-dataset event to zero. The Actor never charges that event manually.

export ACTOR_TEST_PAY_PER_EVENT=true
export APIFY_ACTOR_PRICING_INFO="$(cat examples/pricing_info.local.json)"
export APIFY_CHARGED_ACTOR_EVENT_COUNTS='{"judgment":0,"judgment-with-text":0}'
export ACTOR_MAX_TOTAL_CHARGE_USD=0.03
rm -rf -- ./storage
apify run --input-file examples/chf-common-2026.json

The examples/run-local-ppe.sh sets these three pricing variables and removes ./storage before invoking the CLI. Run it from any directory. Its optional input path is relative to the repository root.

bash examples/run-local-ppe.sh
bash examples/run-local-ppe.sh examples/chf-common-2026.json

The SDK writes simulated receipts to the local charging-log dataset. Delivered rows are in the default dataset. RUN_STATS in the default key-value store contains requests, retries, failed attempts, delivered counts per event, skipped IDs and dates, items_skipped_no_text, UTC start and end times, and duration. items_skipped_no_text counts candidates excluded by the snippet filter after the date and seen-ID checks. failed_requests counts failed attempts, including failures that later succeed on retry.

Tests run offline using recorded API JSON captured on 2026-10-18. They block unmocked HTTP and socket connections. Orchestration tests use a fake Actor to check delivered rows, selected billing events, persistent IDs, and run statistics. They do not exercise real SDK billing in a subprocess. The local command python -m src also reads the standard SDK INPUT from local storage.

Disclaimer

This is an unofficial Actor, not affiliated with SAOS or any Polish court. Source coverage, dates, anonymisation, and text quality depend on the publishing systems. Verify significant findings against the linked judgment.

🇵🇱 Po polsku

Actor wyszukuje orzeczenia sądów w publicznym API SAOS. Zwraca sygnatury, sądy, daty, sędziów, hasła, fragmenty i opcjonalnie pełny opublikowany tekst. Domyślny courtType: ANY obejmuje wszystkie dostępne zbiory. Stan z 2026-10-18: sądy powszechne mają orzeczenia z 2026 roku, SN do czerwca 2016, TK do grudnia 2015, KIO do września 2018. Dla sądów administracyjnych nie znaleziono wyników.

Ustaw dateFrom, dateTo, phrase i maxItems. commonCourtType wymaga courtType: COMMON. includeFullText: true pobiera treść, textFormat wybiera tekst lub HTML, a maxTextChars ogranicza długość. Wynik zawiera oryginalną datę i judgmentDateValid. Domyślnie błędne i przyszłe daty są pomijane bez opłat.

Przy includeFullText: true domyślne onlyWithText: true pomija wyniki z pustym fragmentem po usunięciu HTML i białych znaków. Pominięcie nie pobiera szczegółów, nie zapisuje rekordu, nie nalicza opłaty i nie zapamiętuje identyfikatora. W trybie metadanych filtr jest domyślnie wyłączony. Ustaw jawnie onlyWithText: false, aby zachować wyniki z pustym fragmentem, albo true, aby filtrować także metadane. Niepusty fragment nie gwarantuje pełnej treści. Filtr może wymagać pobrania kolejnych stron, aby osiągnąć maxItems. Liczbę pominięć zawiera RUN_STATS.items_skipped_no_text.

Cena za zapisany rekord wynosi 0,003 USD (judgment) albo 0,010 USD z poprawnie pobraną treścią (judgment-with-text). Błąd pobrania treści zapisuje metadane z textError za 0,003 USD. onlyNew pomija zapamiętane identyfikatory, przechowując ostatnie 50 000. Nie wykrywa zmian treści. Nie uruchamiaj równocześnie zadań z tym samym stateKey.

Actor nie odtwarza danych zanonimizowanych. Pomija strukturalne pola publikujących, weryfikujących i protokolantów, lecz opublikowany tekst może zawierać ich nazwiska. To nieoficjalne narzędzie, a kompletność i aktualność wyników zależą od SAOS.