---
title: "Search Listings"
description: "search_listings tool status"
status: "preview"
canonical_url: "https://fairwayrent.ai/docs/agents/tools/search_listings"
last_updated: "2026-11-04"
related:
  - "/agents"
  - "/docs/agents/tools"
audience: "agents, developers"
---

> For AI agents: Preview: contract may change. The MCP endpoint is coming soon.

# search_listings

Start with the renter's housing request in `query`. Fairway interprets supported criteria as filters and reports what it applied. The worked examples below are illustrative; the input and output schemas follow them and come from the checked-in preview contract.

## Purpose

Find rental listings in SF Bay Area from the renter's housing request.

## When to use / when not to use

Use for a new rental search. Send the housing request, not personal details.

## Access

Preview: contract may change. Planned open access without an API key. The endpoint is coming soon.

## Annotations

`readOnlyHint: true`, `openWorldHint: false` (preview).

## Example request

Illustrative preview only. This is not a callable endpoint.

```json example

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_listings",
    "arguments": {
      "query": "2BR near BART under $3,000, dog friendly, on a quiet street"
    }
  }
}

```

Pin a value with `filters` when it must override what Fairway reads from the query:

```json example

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_listings",
    "arguments": {
      "query": "2BR near BART under $3,000, dog friendly",
      "filters": {
        "rent_max": 280000
      }
    }
  }
}

```

## Example response

Illustrative shape only. Listing IDs, values, and URLs below are examples.

```json example

{
  "applied_filters": {
    "beds_min": 2,
    "rent_max": 300000,
    "pets": "dog"
  },
  "not_applied": [
    "quiet street"
  ],
  "listings": [
    {
      "id": "example-listing-1",
      "status": "available",
      "property": {
        "name": "Example home",
        "address": "Example address"
      },
      "rent_min": 295000,
      "beds_min": 2,
      "checked_at": "2026-10-30T00:00:00Z",
      "listing_url": "https://fairwayrent.ai/property/ca/menlo-park/example",
      "share_url": "https://fairwayrent.ai/property/ca/menlo-park/example"
    }
  ],
  "pagination": {
    "has_next_page": false,
    "limit": 25
  },
  "checked_at_range": {
    "oldest": "2026-10-30T00:00:00Z",
    "newest": "2026-10-30T00:00:00Z"
  },
  "map_url": "https://www.fairwayrent.ai/map?l=example-listing-1"
}

```

## Input schema

| Field | Type | Notes |
| --- | --- | --- |
| `query` | string | The renter's housing request in their own words, such as a two-bedroom near transit under their stated budget that allows dogs. Fairway turns it into filters. Send the housing request, not personal details. |
| `filters` | object | Optional structured fields. Any field here overrides what Fairway took from the query. |
| `bbox` | object | A map box in degrees. If neither filters.area nor query names a metro, Fairway searches the metro that contains the center of the box. |
| `near` | object | A point and radius in meters. For now Fairway searches the box that contains this circle. If neither filters.area nor query names a metro, Fairway searches the metro that contains the point. |
| `pagination` | object | See JSON Schema |

```json example

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "The renter's housing request in their own words, such as a two-bedroom near transit under their stated budget that allows dogs. Fairway turns it into filters. Send the housing request, not personal details.",
      "maxLength": 1000
    },
    "filters": {
      "type": "object",
      "description": "Optional structured fields. Any field here overrides what Fairway took from the query.",
      "properties": {
        "beds_min": {
          "type": "number",
          "minimum": 0,
          "maximum": 20
        },
        "beds_max": {
          "type": "number",
          "minimum": 0,
          "maximum": 20
        },
        "baths_min": {
          "type": "number",
          "minimum": 0,
          "maximum": 20
        },
        "rent_min": {
          "type": "integer",
          "minimum": 0,
          "description": "USD cents",
          "maximum": 10000000
        },
        "rent_max": {
          "type": "integer",
          "minimum": 0,
          "description": "USD cents",
          "maximum": 10000000
        },
        "pets": {
          "type": "string",
          "enum": [
            "dog",
            "cat",
            "none"
          ]
        },
        "move_in_by": {
          "type": "string",
          "format": "date"
        },
        "amenities": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "maxItems": 32
        },
        "area": {
          "type": "string",
          "description": "City, neighborhood, or area to search.",
          "minLength": 1,
          "maxLength": 200
        }
      },
      "additionalProperties": false
    },
    "bbox": {
      "type": "object",
      "description": "A map box in degrees. If neither filters.area nor query names a metro, Fairway searches the metro that contains the center of the box.",
      "properties": {
        "north": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "south": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "east": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        "west": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        }
      },
      "required": [
        "north",
        "south",
        "east",
        "west"
      ],
      "additionalProperties": false
    },
    "near": {
      "type": "object",
      "description": "A point and radius in meters. For now Fairway searches the box that contains this circle. If neither filters.area nor query names a metro, Fairway searches the metro that contains the point.",
      "properties": {
        "lat": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "lng": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        "radius_m": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 50000
        }
      },
      "required": [
        "lat",
        "lng",
        "radius_m"
      ],
      "additionalProperties": false
    },
    "pagination": {
      "type": "object",
      "properties": {
        "cursor": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4096
        },
        "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 25,
          "default": 25,
          "description": "Listings per page. Calls without an API key get at most 5."
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false,
  "required": [
    "query"
  ]
}

```

## Output schema

| Field | Type | Notes |
| --- | --- | --- |
| `applied_filters` | object | Filters Fairway applied from the query and any explicit filters overrides. |
| `not_applied` | array | Parts of the query that did not become a filter, such as quiet street. The agent may use these for its own ranking. |
| `listings` | array | See JSON Schema |
| `pagination` | object | See JSON Schema |
| `checked_at_range` | object | See JSON Schema |
| `map_url` | string | See JSON Schema |

```json example

{
  "type": "object",
  "properties": {
    "applied_filters": {
      "type": "object",
      "description": "Filters Fairway applied from the query and any explicit filters overrides.",
      "properties": {
        "beds_min": {
          "type": "number",
          "minimum": 0
        },
        "beds_max": {
          "type": "number",
          "minimum": 0
        },
        "baths_min": {
          "type": "number",
          "minimum": 0
        },
        "rent_min": {
          "type": "integer",
          "minimum": 0,
          "description": "USD cents"
        },
        "rent_max": {
          "type": "integer",
          "minimum": 0,
          "description": "USD cents"
        },
        "pets": {
          "type": "string",
          "enum": [
            "dog",
            "cat",
            "none"
          ]
        },
        "move_in_by": {
          "type": "string",
          "format": "date"
        },
        "amenities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "area": {
          "type": "string",
          "description": "City, neighborhood, or area to search."
        }
      },
      "additionalProperties": false
    },
    "not_applied": {
      "type": "array",
      "description": "Parts of the query that did not become a filter, such as quiet street. The agent may use these for its own ranking.",
      "items": {
        "type": "string"
      }
    },
    "listings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "const": "available"
          },
          "property": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "address": {
                "type": "string"
              },
              "coordinates": {
                "type": "object",
                "properties": {
                  "lat": {
                    "type": "number"
                  },
                  "lng": {
                    "type": "number"
                  }
                }
              }
            }
          },
          "rent_min": {
            "type": "integer",
            "minimum": 0,
            "description": "USD cents"
          },
          "rent_max": {
            "type": "integer",
            "minimum": 0,
            "description": "USD cents"
          },
          "beds_min": {
            "type": "number"
          },
          "checked_at": {
            "type": "string",
            "format": "date-time"
          },
          "listing_url": {
            "type": "string",
            "format": "uri"
          },
          "share_url": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "id",
          "status",
          "property",
          "checked_at",
          "listing_url",
          "share_url"
        ]
      }
    },
    "pagination": {
      "type": "object",
      "properties": {
        "cursor": {
          "type": "string"
        },
        "has_next_page": {
          "type": "boolean"
        },
        "total_count": {
          "type": "integer",
          "minimum": 0,
          "description": "Estimate, not exact"
        },
        "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 25,
          "description": "Listings per page for this call."
        }
      },
      "required": [
        "has_next_page",
        "limit"
      ]
    },
    "checked_at_range": {
      "type": "object",
      "properties": {
        "oldest": {
          "type": "string",
          "format": "date-time"
        },
        "newest": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "map_url": {
      "type": "string",
      "format": "uri"
    }
  },
  "required": [
    "applied_filters",
    "not_applied",
    "listings",
    "pagination",
    "checked_at_range",
    "map_url"
  ]
}

```

## Errors

These codes come from the MCP service in development. They can change before launch.

A request error is a tool result with `isError: true`. Its `structuredContent` has the HTTP `status`, a `code`, and the `path` of the field at fault. The same JSON is also the text content of the result.

```json example

{
  "status": 400,
  "code": "UNKNOWN_FIELD",
  "path": "filters.radius"
}

```

| Code | Path | Meaning |

| --- | --- | --- |

| `UNKNOWN_FIELD` | The unknown field | The request has a field that the schema does not list. Remove it. |

| `MALFORMED_REQUEST` | The invalid field | A field has the wrong type or is out of range. Fix the value. |

| `UNKNOWN_AMENITY` | `filters.amenities.<index>` | The amenity is not in the filter vocabulary. Remove it or put it in `query`. |

| `CONFLICTING_CRITERIA` | `near` or a filter | The request sends both `bbox` and `near`, or a minimum is above its maximum. |

| `AREA_REQUIRED` | `filters.area` | Neither the request nor `query` names an area. Send `filters.area`, `bbox`, or `near`. |

| `AREA_UNRESOLVED` | `filters.area` | Fairway cannot find the named area. Ask the renter for a city or neighborhood. |

| `UNSUPPORTED_METRO` | `filters.area`, `bbox`, or `near` | The area is outside the metros that Fairway serves. |

| `METRO_NOT_ADMITTED` | `filters.area`, `bbox`, or `near` | Fairway serves the metro, but agent search does not cover it yet. |

| `NO_SEARCH_SCOPE` | `scope` | Fairway could not build a search area from the request. |

| `UNSUPPORTED_CRITERION` | The criterion | Search cannot apply this criterion. Remove it or put it in `query`. |

| `SEARCH_TOO_BROAD` | `filters` | The search matches too much inventory. Add an area or narrower filters. |

| `CURSOR_EXPIRED` | `pagination.cursor` | The cursor is no longer valid. Run the search again without `cursor`. |

If the service times out or cannot read its data, the result has `isError: true` and `{ "error": ... }` with `search_timeout` or `search_unavailable`. Retry later with the same request.

Rate limits and API key problems are not tool results. They are JSON-RPC errors. `error.data.error` names the problem, and `error.code` is the number below for that name. A rate-limit error also has `error.data.retry_after` in seconds and a `Retry-After` header. Wait that long before you retry.

```json example

{
  "rate_limited": -31001,
  "invalid_api_key": -31002,
  "insufficient_scope": -31003
}

```

## Notes for agents

Send the renter’s housing request as they said it, without personal details. Use `filters` only to pin a value. Rank on `not_applied` and your own context. Check `checked_at` before describing availability and link to the Fairway listing.
