---
title: "Get Listing"
description: "get_listing tool status"
status: "preview"
canonical_url: "https://fairwayrent.ai/docs/agents/tools/get_listing"
last_updated: "2026-11-18"
related:
  - "/agents"
  - "/docs/agents/tools"
audience: "agents, developers"
---

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

# get_listing

A field that is missing is unknown, not false. A leased listing has no units. The input and output schemas below are generated from the checked-in preview contract.

## Purpose

Inspect one listing, including property details and available unit evidence.

## When to use / when not to use

Use when a renter wants detail on one known listing. Do not treat unknown fields as promises.

## Access

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

## Annotations

`readOnlyHint: true`, `idempotentHint: 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": "get_listing",
    "arguments": {
      "id": "listing-id"
    }
  }
}

```

## Example response

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

```json example

{
  "id": "listing-id",
  "status": "available",
  "property": {
    "name": "Example property",
    "address": "Example address"
  },
  "units": [
    {
      "id": "unit-id",
      "rent": 295000,
      "beds": 2,
      "baths": 1
    }
  ],
  "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"
}

```

## Input schema

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | See JSON Schema |

```json example

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

```

## Output schema

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | See JSON Schema |
| `status` | string | available has unit detail. leased has an empty units list. |
| `property` | object | See JSON Schema |
| `rent_min` | integer | USD cents |
| `rent_max` | integer | USD cents |
| `beds_min` | number | See JSON Schema |
| `checked_at` | string | See JSON Schema |
| `listing_url` | string | See JSON Schema |
| `share_url` | string | See JSON Schema |
| `units` | array | See JSON Schema |
| `fees` | object | See JSON Schema |
| `policies` | array | See JSON Schema |
| `amenities` | array | See JSON Schema |
| `photos` | array | See JSON Schema |
| `nearby_transit` | array | See JSON Schema |

```json example

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "available",
        "leased"
      ],
      "description": "available has unit detail. leased has an empty units list."
    },
    "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"
    },
    "units": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "rent": {
            "type": "integer",
            "minimum": 0,
            "description": "USD cents"
          },
          "beds": {
            "type": "number"
          },
          "baths": {
            "type": "number"
          },
          "available_at": {
            "type": "string",
            "format": "date"
          }
        }
      }
    },
    "fees": {
      "type": "object",
      "properties": {
        "application": {
          "type": "integer",
          "minimum": 0,
          "description": "USD cents"
        },
        "deposit": {
          "type": "integer",
          "minimum": 0,
          "description": "USD cents"
        },
        "pet_rent": {
          "type": "integer",
          "minimum": 0,
          "description": "USD cents"
        },
        "pet_deposit": {
          "type": "integer",
          "minimum": 0,
          "description": "USD cents"
        },
        "parking": {
          "type": "integer",
          "minimum": 0,
          "description": "USD cents"
        },
        "utilities": {
          "type": "integer",
          "minimum": 0,
          "description": "USD cents"
        }
      }
    },
    "policies": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "amenities": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "photos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "alt": {
            "type": "string"
          }
        },
        "required": [
          "url",
          "alt"
        ]
      },
      "maxItems": 20
    },
    "nearby_transit": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "id",
    "status",
    "checked_at",
    "units"
  ],
  "oneOf": [
    {
      "properties": {
        "status": {
          "const": "available"
        }
      },
      "required": [
        "status",
        "property",
        "listing_url",
        "share_url"
      ],
      "type": "object"
    },
    {
      "properties": {
        "status": {
          "const": "leased"
        },
        "units": {
          "maxItems": 0
        }
      },
      "type": "object",
      "required": [
        "status"
      ]
    }
  ]
}

```

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

| `NOT_FOUND` | `id` | The ID is unknown, merged into another listing, or outside the metros that Fairway serves. Fairway does not follow a merged ID. |

If the service times out or cannot read its data, the result has `isError: true` and `{ "error": ... }` with `listing_timeout` or `listing_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

Check `checked_at` before describing availability. Link to the Fairway listing. Keep renter preferences and ranking in your own context.
