# Otomoto — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Browse and retrieve vehicle listings from otomoto.pl, Poland's leading automotive marketplace. Search by make, model, and category, fetch full listing details and photos, or paginate through bulk results.

**Category:** Automotive | **Website:** [otomoto.pl/](https://otomoto.pl/) | **Docs:** [parse.bot/marketplace/e3d2b436-d4f5-4b61-b9ab-1f2a0ce58ee3/otomoto-pl-api](https://parse.bot/marketplace/e3d2b436-d4f5-4b61-b9ab-1f2a0ce58ee3/otomoto-pl-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/otomoto/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get all listings paginated

Scrape vehicle listings across multiple pages for a given search. Iterates through pages until max_pages is reached or no more results exist. Returns all collected listings in a single response. Useful for bulk collection but slower than single-page search_listings.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Vehicle category slug. |
| `make` | string | No | Vehicle make slug (e.g., volkswagen, toyota, bmw). |
| `max_pages` | integer | No | Maximum number of pages to scrape (1-50). |
| `model` | string | No | Vehicle model slug (e.g., golf, corolla). Requires make to be set. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/otomoto/get-all-listings-paginated \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","make":"<string>","max_pages":"<integer>","model":"<string>"}'
```

### Get categories

Get the fixed list of vehicle categories on otomoto.pl. Returns category slugs (used in URLs and as the category parameter) and their Polish display names. The list is stable and rarely changes.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/otomoto/get-categories \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get listing detail

Retrieve full details for a specific vehicle listing by its URL. Returns a transformed advert object with stable fields: price, description, seller info, equipment categories, images, details, and main features. Volatile upstream fields (parametersDict) are excluded to keep the shape stable across listings.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full URL or path of the listing (e.g., https://www.otomoto.pl/osobowe/oferta/volkswagen-golf-ID6I6lAb.html). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/otomoto/get-listing-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"<string>"}'
```

### Get listing photos

Get all full-resolution photo URLs for a specific listing. Returns an array of direct image URLs extracted from the listing page. Performs the same page fetch as get_listing_detail but returns only the photo URLs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full URL or path of the listing (e.g., https://www.otomoto.pl/osobowe/oferta/volkswagen-golf-ID6I6lAb.html). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/otomoto/get-listing-photos \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"<string>"}'
```

### Search listings

Search vehicle listings on otomoto.pl with optional make, model, and category filters. Returns a paginated page of listing summaries including price, location, and vehicle parameters. Each page contains up to 32 results. Use the page parameter to advance through results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Vehicle category slug. |
| `make` | string | No | Vehicle make slug (e.g., volkswagen, toyota, bmw, aston-martin). |
| `model` | string | No | Vehicle model slug (e.g., golf, corolla, 3-series). Requires make to be set. |
| `page` | integer | No | Page number for pagination (1-based). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/otomoto/search-listings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","make":"<string>","model":"<string>","page":"<integer>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.