docs: Add guide on validating Actor input with Pydantic (#941)

Adds a guide on validating Actor input with
[Pydantic](https://docs.pydantic.dev/), so Actor code works with a
typed, guaranteed-valid object instead of reaching into a raw input
dictionary. Follows the structure of the existing guides.

- `docs/03_guides/11_pydantic.mdx` — the guide: why raw-dict access is
fragile, defining an input model (aliases bridging
`camelCase`↔`snake_case`, defaults, constraints, a custom validator,
`extra='ignore'`), validating with `model_validate` and failing fast on
`ValidationError`, the relationship to the platform input schema, and a
few extra features (`HttpUrl`/`EmailStr`, `model_validator`,
`SecretStr`).
- `code/11_pydantic.py` — the runnable example Actor (Run on Apify),
plus the `11_http_url.py`, `11_model_validator.py`, and
`11_raw_input.py` snippets.
- Cross-links added to the **Actor input** concepts page and the
quick-start guides list.

Verified locally for valid input (passes validation, writes `OUTPUT`,
exit 0) and invalid input (per-field summary keyed by input-schema
alias, run ends FAILED). Lint + type-check pass.

Author: vdusek

docs/01_introduction/quick-start.mdx

@@ -109,3 +109,4 @@ To see how you can integrate the Apify SDK with popular web scraping libraries,
 - [Browser Use](../guides/browser-use)
 - [Running webserver](../guides/running-webserver)
 - [uv](../guides/uv)
+- [Validate Actor input with Pydantic](../guides/input-validation)

docs/02_concepts/02_actor_input.mdx

@@ -20,6 +20,10 @@ For example, if an Actor received a JSON input with two fields, `{ "firstNumber"
     {InputExample}
 </RunnableCodeBlock>
 
+## Validating input
+
+Reading values straight out of the raw input dictionary works for simple cases, but it gives you no type guarantees, no constraint checks, and no clear error when the input is malformed. For anything beyond a couple of fields, validate the input with [Pydantic](https://docs.pydantic.dev/). Your code then works with a typed, guaranteed-valid object instead. For the recommended approach, see [Validate Actor input with Pydantic](../guides/input-validation).
+
 ## Loading URLs from Actor input
 
 Actors commonly receive a list of URLs to process via their input. The <ApiLink to="class/ApifyRequestList">`ApifyRequestList`</ApiLink> class (from `apify.request_loaders`) can parse the standard Apify input format for URL sources. It supports both direct URL objects (`{"url": "https://example.com"}`) and remote URL lists (`{"requestsFromUrl": "https://example.com/urls.txt"}`), where the remote file contains one URL per line.

docs/03_guides/11_pydantic.mdx

@@ -0,0 +1,122 @@
+---
+id: input-validation
+title: Input validation with Pydantic
+description: Parse, validate, and type your Actor's input with Pydantic models instead of reaching into a raw dictionary.
+---
+
+import CodeBlock from '@theme/CodeBlock';
+import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
+import ApiLink from '@theme/ApiLink';
+
+import RawInputExample from '!!raw-loader!roa-loader!./code/11_raw_input.py';
+import PydanticExample from '!!raw-loader!roa-loader!./code/11_pydantic.py';
+import HttpUrlExample from '!!raw-loader!./code/11_http_url.py';
+import ModelValidatorExample from '!!raw-loader!./code/11_model_validator.py';
+import SecretStrExample from '!!raw-loader!./code/11_secret_str.py';
+
+In this guide, you'll learn how to validate your Apify Actor's input with [Pydantic](https://docs.pydantic.dev/), so that your code works with a typed, guaranteed-valid object instead of a raw dictionary.
+
+## Introduction
+
+An Actor reads its input with <ApiLink to="class/Actor#get_input">`Actor.get_input`</ApiLink>, which returns the input record as a plain `dict`. Working with that dictionary directly is fragile:
+
+<RunnableCodeBlock className="language-python" language="python">
+    {RawInputExample}
+</RunnableCodeBlock>
+
+- There are no type guarantees. `max_results` can arrive as the string `"10"` or `None` and you won't know until something breaks.
+- There's no validation. Nothing stops `max_results` from being `0` or `-5`, or `search_terms` from being empty.
+- A typo in a key, like `maxResult` instead of `maxResults`, silently falls back to the default instead of failing.
+- Defaults are scattered across the codebase, and your editor can't autocomplete the fields or catch mistakes.
+
+[Pydantic](https://docs.pydantic.dev/) solves all of these problems. You declare the shape of your input once as a model, and Pydantic parses the raw dictionary into a typed object, applies defaults, enforces constraints, and produces clear error messages when the input doesn't match.
+
+To use Pydantic, install it into your Actor's environment:
+
+```bash
+pip install pydantic
+```
+
+## Example Actor
+
+The following Actor declares its input as a Pydantic `BaseModel`, validates the raw input against it, and then works with a fully typed object. On invalid input it fails fast with a readable error. On valid input it logs the normalized values and stores them as the Actor's output.
+
+<RunnableCodeBlock className="language-python" language="python">
+    {PydanticExample}
+</RunnableCodeBlock>
+
+### About the model
+
+- Apify input fields conventionally use camel case (`maxResults`), while Python attributes use snake case (`max_results`). Since every field follows that convention, `alias_generator=to_camel` derives the camel case alias for the whole model at once, instead of spelling out `Field(alias=...)` on each field. `populate_by_name=True` lets the model accept either spelling, which is handy in tests.
+- A field without a default (`search_terms`) is required. A field with a default (`max_results`) is optional. There's a single, obvious place where every default lives.
+- `ge=1, le=100` enforces a numeric range, `min_length=1` rejects an empty list, and `Literal['json', 'csv']` restricts a field to a fixed set of choices, mirroring an `enum` in the input schema.
+- The `field_validator` normalizes the search terms (trimming whitespace, dropping empties) and rejects input that has nothing left. The rest of your code never has to repeat those checks.
+- `extra='ignore'` means adding a new field to your input schema won't break an older Actor build that doesn't know about it yet. Use `extra='forbid'` instead if you prefer to reject anything unexpected.
+
+### About the validation
+
+- `model_validate` parses the raw dictionary into a typed `ActorInput` instance. It fills in defaults and guarantees every field is valid, or raises a `ValidationError` that describes every problem at once.
+- Catching that error, logging a readable summary, and re-raising makes the Actor fail fast with a clear explanation right at the start, rather than crashing with an obscure error somewhere deep in the run. Because the body runs inside `async with Actor:`, the re-raised exception automatically marks the run as `FAILED`.
+- The error messages refer to the fields by their input-schema aliases. For invalid input like `{"searchTerms": [], "maxResults": 999, "outputFormat": "xml"}`, the log shows exactly what's wrong:
+
+  ```text
+  The Actor input is invalid:
+  3 validation errors for ActorInput
+  searchTerms
+    List should have at least 1 item after validation, not 0 ...
+  maxResults
+    Input should be less than or equal to 100 ...
+  outputFormat
+    Input should be 'json' or 'csv' ...
+  ```
+
+Once validation passes, the rest of `main` works with `actor_input.search_terms`, `actor_input.max_results`, and `actor_input.output_format`, all correctly typed, with editor autocompletion and static type checking.
+
+## Relationship to the input schema
+
+Pydantic validation complements the Actor's [input schema](https://docs.apify.com/platform/actors/development/input-schema) (`.actor/input_schema.json`). It doesn't replace it. The two serve different layers:
+
+- The input schema drives the [Apify Console](https://console.apify.com/) form, documents the fields for your users, and lets the platform validate input before the run even starts. Keep declaring your fields there.
+- The Pydantic model validates the input again inside your Python code, where it gives you a typed object, IDE support, and richer rules (normalization, cross-field checks, custom formats) that the input schema can't express. It's also your safety net for runs started programmatically by [another Actor](../concepts/interacting-with-other-actors) or executed [locally](https://docs.apify.com/cli/docs/reference#apify-run), and for keeping the two definitions honest with each other.
+
+Keep the model's aliases in sync with the field keys in `input_schema.json`, and the two definitions describe the same input from both sides.
+
+## Useful validation features
+
+Pydantic offers extra features for validating Actor input. For the full set of types, constraints, and validators, see the [Pydantic documentation](https://docs.pydantic.dev/latest/concepts/models/).
+
+### Format-validated types
+
+For common string formats, for example `HttpUrl` for URLs or `EmailStr` for e-mail addresses, use format-validated types:
+
+<CodeBlock className="language-python">
+    {HttpUrlExample}
+</CodeBlock>
+
+### Cross-field validation
+
+When one field's validity depends on another, use `model_validator`:
+
+<CodeBlock className="language-python">
+    {ModelValidatorExample}
+</CodeBlock>
+
+### Secret input fields
+
+The platform decrypts [secret input fields](https://docs.apify.com/platform/actors/development/secret-input) for you before <ApiLink to="class/Actor#get_input">`Actor.get_input`</ApiLink> returns, so you receive plaintext. To keep them from leaking into logs or `model_dump()` output, wrap such fields in Pydantic's `SecretStr` and read the plaintext with `get_secret_value()` when you actually need it:
+
+<CodeBlock className="language-python">
+    {SecretStrExample}
+</CodeBlock>
+
+## Conclusion
+
+In this guide, you learned how to validate Actor input with Pydantic: declaring the input as a model with aliases, defaults, and constraints, parsing the raw input with `model_validate`, failing fast with a readable error when the input is invalid, and working with a typed object for the rest of the run. To get started with your own Actors, see the [Actor templates](https://apify.com/templates/categories/python). If you have questions or need assistance, feel free to reach out on our [GitHub](https://github.com/apify/apify-sdk-python) or join our [Discord community](https://discord.com/invite/jyEM2PRvMU). Happy validating!
+
+## Additional resources
+
+- [Pydantic: Official documentation](https://docs.pydantic.dev/)
+- [Pydantic: Models](https://docs.pydantic.dev/latest/concepts/models/)
+- [Pydantic: Validators](https://docs.pydantic.dev/latest/concepts/validators/)
+- [Apify: Actor input](https://docs.apify.com/platform/actors/running/input)
+- [Apify: Input schema specification](https://docs.apify.com/platform/actors/development/input-schema)

docs/03_guides/code/11_http_url.py

@@ -0,0 +1,7 @@
+from pydantic import BaseModel, EmailStr, HttpUrl
+
+
+class ActorInput(BaseModel):
+    target_url: HttpUrl
+    # `EmailStr` needs the `pydantic[email]` extra installed.
+    contact_email: EmailStr

docs/03_guides/code/11_model_validator.py

@@ -0,0 +1,14 @@
+from typing import Self
+
+from pydantic import BaseModel, model_validator
+
+
+class ActorInput(BaseModel):
+    min_price: int = 0
+    max_price: int = 100
+
+    @model_validator(mode='after')
+    def _check_range(self) -> Self:
+        if self.min_price > self.max_price:
+            raise ValueError('min_price must not exceed max_price')
+        return self

docs/03_guides/code/11_pydantic.py

@@ -0,0 +1,63 @@
+import asyncio
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
+from pydantic.alias_generators import to_camel
+
+from apify import Actor
+
+
+class ActorInput(BaseModel):
+    """Typed and validated representation of the Actor input."""
+
+    # Derive each field's camelCase alias (searchTerms, maxResults, ...) automatically;
+    # accept both spellings and ignore extras.
+    model_config = ConfigDict(
+        populate_by_name=True, extra='ignore', alias_generator=to_camel
+    )
+
+    # Required: non-empty list of search terms (normalized below).
+    search_terms: list[str] = Field(min_length=1)
+
+    # Optional: 1-100, defaults to 10.
+    max_results: int = Field(default=10, ge=1, le=100)
+
+    # Optional: restricted to a fixed set of choices.
+    output_format: Literal['json', 'csv'] = Field(default='json')
+
+    @field_validator('search_terms')
+    @classmethod
+    def _normalize_terms(cls, value: list[str]) -> list[str]:
+        # Trim whitespace and drop empty terms.
+        cleaned = [term.strip() for term in value if term.strip()]
+        if not cleaned:
+            raise ValueError('searchTerms must contain at least one non-empty term')
+        return cleaned
+
+
+async def main() -> None:
+    async with Actor:
+        # Read the raw input (a plain dict, not yet validated).
+        raw_input = await Actor.get_input() or {}
+
+        # Validate the raw input against the model.
+        try:
+            actor_input = ActorInput.model_validate(raw_input)
+        except ValidationError as exc:
+            # Log a per-field summary, then re-raise to fail the run.
+            Actor.log.error('The Actor input is invalid:\n%s', exc)
+            raise
+
+        # Work with typed attributes from here on.
+        Actor.log.info('Input passed validation: %s', actor_input.model_dump())
+
+        max_results = actor_input.max_results
+        for term in actor_input.search_terms:
+            Actor.log.info('Processing %r (max %d results)', term, max_results)
+
+        # Store the normalized input as output.
+        await Actor.set_value('OUTPUT', actor_input.model_dump())
+
+
+if __name__ == '__main__':
+    asyncio.run(main())

docs/03_guides/code/11_raw_input.py

@@ -0,0 +1,18 @@
+import asyncio
+
+from apify import Actor
+
+
+async def main() -> None:
+    # Enter the context of the Actor.
+    async with Actor:
+        # Read the input and reach into the raw dict.
+        actor_input = await Actor.get_input() or {}
+        search_terms = actor_input.get('searchTerms', [])
+        max_results = actor_input.get('maxResults', 10)
+
+        Actor.log.info('search_terms=%s, max_results=%s', search_terms, max_results)
+
+
+if __name__ == '__main__':
+    asyncio.run(main())

docs/03_guides/code/11_secret_str.py

@@ -0,0 +1,10 @@
+from pydantic import BaseModel, SecretStr
+
+
+class ActorInput(BaseModel):
+    # Masked in logs and `model_dump()`; read the plaintext with `get_secret_value()`.
+    api_token: SecretStr
+
+
+actor_input = ActorInput.model_validate({'api_token': 'my-secret-token'})
+token = actor_input.api_token.get_secret_value()

src/apify/_actor.py

@@ -699,7 +699,15 @@ async def push_data(self, data: dict | list[dict], *, charged_event_name: str |
 
     @_ensure_context
     async def get_input(self) -> Any:
-        """Get the Actor input value from the default key-value store associated with the current Actor run."""
+        """Get the Actor input value from the default key-value store associated with the current Actor run.
+
+        The input is the deserialized contents of the input record (the `INPUT` key by default), so it is typically
+        a `dict` keyed by the fields declared in the Actor's input schema. Any secret input fields are decrypted to
+        plaintext before being returned.
+
+        Returns:
+            The Actor input, usually a `dict` of input fields, or `None` if the Actor has no input.
+        """
         input_value = await self.get_value(self.configuration.input_key)
         input_secrets_private_key = self.configuration.input_secrets_private_key_file
         input_secrets_key_passphrase = self.configuration.input_secrets_private_key_passphrase

website/versioned_docs/version-3.4/01_introduction/quick-start.mdx

@@ -109,3 +109,4 @@ To see how you can integrate the Apify SDK with popular web scraping libraries,
 - [Browser Use](../guides/browser-use)
 - [Running webserver](../guides/running-webserver)
 - [uv](../guides/uv)
+- [Validate Actor input with Pydantic](../guides/input-validation)