Payload

One job’s body, for any source.

Usage

Source

Payload()

Payload types each parameter that keeps one name, placement, type and value set on every source that takes it. Any other keyword goes into the body as it is, so a source without a model of its own still runs. An unset field stays out of the body, so the API applies its own default. A payload sets exactly one input key, to a non-empty string. Otherwise it raises only for a mistake that the API would bill, and leaves each free check to the API.

Attributes

source: str

The source that runs the job. It takes any string, because the API rejects an unknown source for free.

query: str | None

The input of most search and product sources.

url: str | None

The input of universal and of the sources that take a page’s URL.

product_id: str | None

The input of product sources such as walmart_product.

prompt: str | None

The input of chatgpt, gemini and perplexity.

video_id: str | None

The input of youtube_video_trainability.

channel_handle: str | None

The input of youtube_channel.

category_id: str | None

The input of target_category.

render: Literal["html", "png", ""] | None

html or png renders the page in a browser, and "" turns off forced rendering.

user_agent_type: _UserAgentType | None

The device of the job’s user agent. A desktop_* value draws from the same agents as desktop.

callback_url: str | None

The URL that the API calls when the job finishes.

parse: bool | None

Returns parsed content, which needs a dedicated parser, parsing_instructions or parser_preset.

start_page: PositiveInt | None

The first page to fetch.

pages: PositiveInt | None

The number of pages to fetch, each billed as one result.

limit: int | None

The number of results on each page, or of videos on youtube_channel.

markdown: bool | None

Makes Markdown the default output type.

xhr: bool | None

Makes the page’s Fetch and XHR requests the default output type, and needs render.

parser_preset: str | None

The parser preset to parse with, which needs parse.

content_encoding: Literal["base64", "utf-8"] | None

base64 returns an image as Base64 text.

client_notes: str | None

Text that the API saves with the job.

aggregate_name: str | None

The Result Aggregator that receives the result.

geo_location: str | None

The location that the job appears to come from, in a format that depends on the source.

locale: str | None

The language of the page, such as en_US on Amazon or de-DE on Google.

domain: str | None

The target’s domain, such as de for amazon.de.

context: list[_ContextItem] | None

key and value items that the API reads from the context list.

storage_type: Literal["gcs", "s3", "tos", "s3_compatible"] | None

The Cloud Storage type that uploads the result, with Push-Pull only. Only gcs has a live upload test.

storage_url: str | None

The bucket path that Cloud Storage uploads to. A path that ends in .{{ extension }} names each job’s object, so it raises without { job_id }: jobs that share a name lose their uploads and still bill. repr, validation errors and dry_run show its credentials as redacted:redacted, as the API does. The API returns a free 400 for a raw /, ? or # in the secret, and accepts it percent-encoded. A document that is not valid JSON fails before any Payload code runs, so only Payload.model_validate_json redacts that error. A caller’s TypeAdapter or model that holds a Payload keeps the whole document in errors() and json(), credentials included.

parsing_instructions: (
    Annotated[
        ParsingInstructions, PlainValidator(_parsing_instructions), WithJsonSchema({})
    ]
    | None
)

The instructions of a custom parser, which need parse. A wrong _args shape, or a regex that Python’s re cannot compile, raises, because the API bills it with a null field.

browser_instructions: list[BrowserInstruction] | None

The browser actions to run on the page, which need render. An instruction after fetch_resource, or a filter that Python’s re cannot compile, raises, because the API returns 500 for it on every attempt.

extra: dict[str, Any]

Keys in the API’s shape, which oxy merges into the body. Its context items follow the typed ones, and a key set both here and as a field raises. It also carries a value that an out-of-date Literal rejects.