---
title: "Search the SF rental index; every row carries source and last-seen date. Partner keys get the free sample tier, never the full index."
method: GET
path: "/v1/listings"
tags: ["rental_readiness"]
---

# Search the SF rental index; every row carries source and last-seen date. Partner keys get the free sample tier, never the full index.

`GET /v1/listings`

## Request

- Base URL: `https://www.putroots.com`
- URL: `https://www.putroots.com/v1/listings`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Search PutRoots' San Francisco rental index. Every row carries its source, the date we last saw it, and whether the landlord stated any requirements at all. Use this when someone asks what's available in SF at a price / bedroom count / neighborhood. Without a signed-in PutRoots account this searches the free sample only (3 listings per bedroom tier) and says so, with the true total.

## Query parameters

- `max_price` number
- `min_price` number
- `beds` 'room' | 'studio' | '1' | '2' | '3+'
- `hood` string
- `limit` integer

## Response `200`

OK

- object
  - `source` unknown, required
  - `fetched_at` string, date-time, required
  - `gated` boolean, required: true = free sample only (anonymous or partner key); total still tells the true index size.
  - `total` integer, required
  - `searched` integer, required
  - `matched` integer, required
  - `not_checked_vs_budget` integer
  - `listings_with_no_stated_requirements` integer
  - `listings` object[], required
    - `url` string, required
    - `title` string, nullable
    - `price` number, nullable, required
    - `beds` string, nullable
    - `hood` string, nullable
    - `source` string, nullable, required
    - `posted` string, nullable
    - `last_seen` string, nullable
    - `requirements_stated` boolean, required
    - `not_checked_vs_budget` boolean

## Other responses

- `400`: Bad input — error says which field.
- `401`: No key / bad token.
- `403`: Key is fine but not for this: pending approval, revoked, scope missing, or an operation only the renter's own account may call.
- `404`: No such lead / hand-off / listing under this key.
- `409`: Conflict: the code is already registered.
- `429`: Rate limited; Retry-After in seconds.

---

[API](https://skmtc.dev/putroots/apis/putroots-api.md) · [All operations](https://skmtc.dev/putroots/apis/putroots-api/llms.txt) · [OpenAPI document](https://skmtc.dev/putroots/apis/putroots-api/revisions/a859d719878d?raw)