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

# Demand & Intent — Condition endpoints reference

> Top games wanted in a specific condition (loose, CIB, new, any). See which titles have the most buyer demand by listing condition. Scope: demand-intent.read.

The condition endpoints let you see which games buyers most want in a specific condition — **loose** (cartridge or disc only, no box or manual), **CIB** (complete in box — game, box, and manual), **new** (sealed or unused), or **any** (no condition preference specified). If you are deciding whether to list a copy of a game as loose or hold it to sell CIB, this is the data to check first. All endpoints on this page require the `demand-intent.read` scope and a valid `Authorization: Bearer <token>` header.

## How condition demand is measured

Condition demand comes from **notification alerts** — watchlist saves where a buyer explicitly selects the condition they want before setting a price-drop alert. This captures both the game ID *and* the buyer's desired condition in a single signal, making it the most precise source of condition-specific intent available. It is separate from search demand (which can carry condition keywords but is not tied to a game ID).

The `any` bucket is a derived condition: it represents alerts saved with no condition filter — an "indifferent" buyer who will accept any condition at the right price.

<Note>
  Condition ranks are computed **per condition**, not across the full catalog. The rank-1 game in `loose` is the most-wanted loose title; the rank-1 game in `cib` is the most-wanted CIB title. The same game can rank #1 in `loose` and #5 in `cib` — the leaderboards are independent.
</Note>

***

## GET /api/v1/demand-intent/conditions/{condition}

Returns a ranked leaderboard of games most wanted in the specified condition, for the selected period. Use this when you have inventory to list and want to know which condition will attract the most buyers.

```bash theme={null}
curl -s "https://api.8bitedge.com/api/v1/demand-intent/conditions/loose" \
  -H "Authorization: Bearer $TOKEN" | jq
```

### Valid condition values

| Value   | Buyer intent                             |
| ------- | ---------------------------------------- |
| `loose` | Cartridge or disc only, no box or manual |
| `cib`   | Complete in box — game, box, and manual  |
| `new`   | Sealed or unused                         |
| `any`   | No condition preference specified        |

Any other value for `{condition}` returns `404 not_found`.

### Path parameters

<ParamField path="condition" type="string" required>
  The condition to filter by. Must be one of `loose`, `cib`, `new`, or `any`.
</ParamField>

### Query parameters

<ParamField query="period" type="string" default="7d">
  The time window to aggregate over. One of `day`, `7d`, or `30d`.
</ParamField>

<ParamField query="console_id" type="integer">
  Filter results to games belonging to this console.
</ParamField>

<ParamField query="date" type="string">
  Override the target date. Defaults to the latest computed date. Format: `YYYY-MM-DD`.
</ParamField>

<ParamField query="limit" type="integer" default="25">
  Page size. Capped by your plan's `max_page_size`.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number (page-mode pagination).
</ParamField>

<ParamField query="cursor" type="string">
  Cursor token for cursor-mode pagination. Pass `paginate=cursor` to opt in.
</ParamField>

<ParamField query="paginate" type="string" default="page">
  Set to `cursor` for cursor-based pagination.
</ParamField>

### Response

<ResponseField name="data" type="array">
  Paginated array of game rows ranked within the selected condition.

  <ResponseField name="rank" type="integer">
    The game's rank within this condition's leaderboard for the period. Ranking is per-condition and independent of other conditions.
  </ResponseField>

  <ResponseField name="game" type="object">
    Game identity fields.

    <ResponseField name="id" type="integer">Unique game ID.</ResponseField>
    <ResponseField name="name" type="string">Display name of the game.</ResponseField>
    <ResponseField name="slug" type="string">URL slug for the game.</ResponseField>
    <ResponseField name="console_id" type="integer">ID of the console this game belongs to.</ResponseField>
    <ResponseField name="console_name" type="string">Display name of the console.</ResponseField>
  </ResponseField>

  <ResponseField name="watch" type="object">
    Watchlist and alert metrics for this game in the selected condition.

    <ResponseField name="watch_count" type="integer">Number of active alerts for this game in this condition.</ResponseField>
    <ResponseField name="update_count" type="integer">Number of price-drop notification triggers for this game in this condition.</ResponseField>
    <ResponseField name="condition_share" type="float">This condition's share of all alerts across the game's four conditions (0.0–1.0). This reflects how concentrated buyer demand for this game is on this particular condition — not this game's share of the leaderboard.</ResponseField>
    <ResponseField name="distinct_users" type="integer">Unique users with an alert for this game in this condition.</ResponseField>
    <ResponseField name="mobile_share" type="float">Fraction of alert activity from mobile devices (0.0–1.0).</ResponseField>
  </ResponseField>

  <ResponseField name="pricing" type="object">
    Current market prices from the catalog.

    <ResponseField name="loose" type="string">Loose price as a decimal string.</ResponseField>
    <ResponseField name="complete" type="string">Complete-in-box price as a decimal string.</ResponseField>
    <ResponseField name="new" type="string">Sealed/new price as a decimal string.</ResponseField>
  </ResponseField>
</ResponseField>

<ResponseField name="meta" type="object">
  <ResponseField name="period" type="string">The resolved period (`day`, `7d`, or `30d`).</ResponseField>
  <ResponseField name="period_date" type="string">The date the data was computed for (YYYY-MM-DD).</ResponseField>
  <ResponseField name="condition" type="string">The active condition filter.</ResponseField>
  <ResponseField name="sort" type="string">Always `"watches"` for this endpoint.</ResponseField>
  <ResponseField name="pagination" type="object">Standard pagination metadata.</ResponseField>
</ResponseField>

**Example — `GET /api/v1/demand-intent/conditions/loose`:**

```json theme={null}
{
  "data": [
    {
      "rank": 1,
      "game": {
        "id": 412,
        "name": "Chrono Trigger",
        "slug": "chrono-trigger",
        "console_id": 19,
        "console_name": "Nintendo SNES"
      },
      "watch": {
        "watch_count": 48,
        "update_count": 64,
        "condition_share": 0.75,
        "distinct_users": 41,
        "mobile_share": 0.38
      },
      "pricing": { "loose": "40.00", "complete": "95.50", "new": "300.00" }
    }
  ],
  "meta": {
    "period": "7d",
    "period_date": "2026-06-16",
    "condition": "loose",
    "sort": "watches",
    "pagination": { "mode": "page", "page": 1, "per_page": 25, "total": 320, "last_page": 13 }
  },
  "links": { "next": "https://api.8bitedge.com/api/v1/demand-intent/conditions/loose?page=2", "prev": null }
}
```

In the example above, `condition_share: 0.75` means 75% of all alerts for Chrono Trigger (across all four conditions) are for the loose version — buyers for this title strongly prefer to own the cartridge alone rather than wait for a boxed copy.

<Tip>
  To see all four conditions side-by-side for a single game — rather than browsing by condition — use [`GET /api/v1/demand-intent/games/{game_id}/conditions`](/api/demand-games#get-apiv1demand-intentgamesgame_idconditions). That endpoint shows you the full condition breakdown ranked within one game, and is the fastest way to answer "for *this* specific title, should I list it loose or CIB?"
</Tip>