# Spb Cian — 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.

> Search for available flats for sale and rent across St. Petersburg directly from CIAN.ru's listing database. Retrieve detailed real estate information to compare properties, prices, and rental options in your desired neighborhoods.

**Category:** Real Estate | **Website:** [spb.cian.ru/map/?center=59.95490463888957%2C30.27990534980158&deal_type=sale&electronic_trading=2&engine_version=2&flat_share=2&hand_over=1&min_ceiling_height=3&mintarea=75&offer_type=flat&only_flat=1&region=2&sort=price_object_order&zoom=12](https://spb.cian.ru/map/?center=59.95490463888957%2C30.27990534980158&deal_type=sale&electronic_trading=2&engine_version=2&flat_share=2&hand_over=1&min_ceiling_height=3&mintarea=75&offer_type=flat&only_flat=1&region=2&sort=price_object_order&zoom=12) | **Docs:** [parse.bot/marketplace/608a09c6-6f44-42de-9854-a7742aee15e4/spb-cian-ru-api](https://parse.bot/marketplace/608a09c6-6f44-42de-9854-a7742aee15e4/spb-cian-ru-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/spb-cian/`
**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

### Search flats

Search flats for sale or long-term rent in St. Petersburg. Returns paginated results with detailed property information including price, area, floor, address, coordinates, metro stations, and building characteristics. Each page returns up to 28 listings. Results are auto-iterated by the SDK.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `deal_type` | string | No | Type of deal. |
| `max_area` | number | No | Maximum total area in square meters. |
| `max_floor` | integer | No | Maximum floor number. |
| `max_price` | integer | No | Maximum price in rubles. |
| `min_area` | number | No | Minimum total area in square meters. |
| `min_ceiling_height` | number | No | Minimum ceiling height in meters (e.g. 2.7, 3.0). |
| `min_floor` | integer | No | Minimum floor number. |
| `min_price` | integer | No | Minimum price in rubles. |
| `page` | integer | No | Page number for pagination, starting from 1. |
| `room_type` | string | No | Filter by property type: 'flat' for flats only (excludes apartments), 'apartment' for apartments only. Omit for all types. |
| `rooms` | string | No | Comma-separated list of room counts to filter by (e.g. '1,2,3'). Studio is 9. |
| `sort` | string | No | Sort order for results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/spb-cian/search-flats \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"deal_type":"<string>","max_area":"<number>","max_floor":"<integer>","max_price":"<integer>","min_area":"<number>","min_ceiling_height":"<number>","min_floor":"<integer>","min_price":"<integer>","page":"<integer>","room_type":"<string>","rooms":"<string>","sort":"<string>"}'
```

## 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.