> ## Documentation Index
> Fetch the complete documentation index at: https://developers.investorlift.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Listing cycle object

> One cycle of a house on the market: when it went active, how the price moved, and how the cycle ended.

One period a house is on the market, cut from the weekly listing events.
[`GET /v1/properties/{property_id}/listing-history`](/api-reference/endpoints/properties-listing-history) returns it.
A [parcel search row](/api-reference/objects/parcel-search-row) carries the counts `history.listing_cycles_1y` and
`history.price_cuts_current_listing`.

A cycle opens the first week the replay sees the parcel on the market. It closes when the parcel sells or comes off.
The next time the parcel goes active, a new cycle opens with `cycle_no` one higher. So a house listed, withdrawn and
relisted is two cycles.

## Outcome

| `outcome`    | Means                                                                        |
| ------------ | ---------------------------------------------------------------------------- |
| `sold`       | It sold, and `sold_price` and `sold_on` are not null.                        |
| `canceled`   | The feed's status read canceled.                                             |
| `expired`    | The listing agreement expired.                                               |
| `withdrawn`  | The feed's status read withdrawn.                                            |
| `off_market` | It came off without one of the words above.                                  |
| `active`     | Still on the market in the last week replayed.                               |
| `unknown`    | The last status was neither active nor terminal, so how it ended is unknown. |

The four middle rows are one fact in four of the feed's words: it came off the market without a sale. Group them
when you count, and show the word when you explain one house.

## The fields a reader misreads

* **`original_price` is the first price this replay saw**, not necessarily the first price the house ever asked.
  On a house already listed when the replay began, at `meta.coverage[].parcel.history.first_week`, it is the price
  in that week's file.
* **`days_on_market` is accurate to the week.** It runs from `listed_on` to `sold_on`, or to the last event week
  while the cycle is open. The events behind it are weekly observations.
* **`first_week` against `listed_on`.** `first_week` is when the replay saw the cycle. `listed_on` is the date the
  feed itself carried and can be earlier.
* **`n_price_cuts` and `n_price_rises` count moves, not dollars.** `original_price`, `min_price` and `last_price`
  are the dollars.
* **`price_path[]` is the drawable series**: every listing event of the cycle in order, each with its week, price,
  status and event kind. A null price in it is a week whose record carried none.
* **`status_path[]` is the distinct statuses in order**, so a status repeated over many weeks appears once.

## Contact data

This host serves neither `agent_name` nor `agent_license`, so a cycle carries neither key. The first is the first
listing agent as the file named it. The second is the state licence number, where the 2025 files carried one. The
parcel's listing block identifies its agent by `agent_id`, the key to [the Listing agent object](/api-reference/objects/agent).


## Related topics

- [Read the listing cycles of a parcel](/api-reference/properties/read-the-listing-cycles-of-a-parcel.md)
- [Read a parcel's listing cycles](/api-reference/endpoints/properties-listing-history.md)
- [The Listing agent object](/api-reference/objects/agent.md)
- [The Investorlift listing object](/api-reference/objects/wholesale-listing.md)
- [The twenty-six tools](/mcp/tools.md)