---
name: oxyscraper
description: >
  Unofficial Python library and CLI for the Oxylabs Web Scraper API. Use when writing Python code that uses the oxyscraper package.
license: MIT
compatibility: Requires Python >=3.11.
---

# oxyscraper

Unofficial Python library and CLI for the Oxylabs Web Scraper API.

## Installation

```bash
pip install oxyscraper
```

## API overview

### Classes

Core classes

- `Amazon`: An `amazon` job, which scrapes an Amazon URL
- `AmazonBestsellers`: An `amazon_bestsellers` job, which scrapes the Best Sellers page of one browse node
- `AmazonPricing`: An `amazon_pricing` job, which scrapes the offers of one product
- `AmazonProduct`: An `amazon_product` job, which scrapes one product page
- `AmazonSearch`: An `amazon_search` job, which scrapes the results of one search
- `AmazonSellers`: An `amazon_sellers` job, which scrapes one seller's page
- `Payload`: One job's body, for any source
- `Universal`: A `universal` job, which scrapes any URL
- `AsyncRun`: The jobs of one `AsyncSession.stream` call, each as it finishes
- `AsyncSession`: Submit payloads and fetch their jobs inside an `async with` block, on asyncio or trio
- `Run`: The jobs of one run, each as it finishes
- `Session`: Submit payloads and fetch their jobs from sync code, inside a `with` block

### Dataclasses

Data-holding classes

- `DryRun`: The jobs a run would submit
- `Job`: One job and its results
- `Progress`: The number of a run's payloads in each state, at one moment
- `Rejection`: The error that the API returned for a payload instead of a job, so nothing billed
- `Result`: One page of a job's results, in one output type
- `Upload`: A job's Cloud Storage upload

### Exceptions

Exception classes

- `IncompleteRunError`: The error a run raises after its last job, when a payload ended with no done or faulted job, an upload failed, or a failure stopped the run
- `OxylabsError`: One error response from the API, or a network failure that lasted past the retry limit

### Functions

Public functions

- `dry_run`: List the jobs that a run of `payloads` would submit, and the most results they can bill

### Constants

Module-level constants and data

- `SOURCES`: Built-in immutable sequence
- `BrowserInstruction`: Runtime representation of an annotated type
- `ParsingFunction`: Represent a PEP 604 union type
- `ParsingInstructions`: Create named, parameterized type aliases

## Resources

- [Full documentation](https://ozanozbeker.com/oxyscraper/)
- [llms.txt](llms.txt) — Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs
- [Source code](https://github.com/ozanozbeker/oxyscraper)