> ## 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 — Search endpoints reference

> Search demand leaderboards, trending queries, unmet demand (supply gaps), and market-wide condition mix. Scope: demand-intent.read.

The search demand endpoints surface what buyers are actively looking for by free-text query — including which searches are rising in popularity, which high-volume queries are returning little or no inventory (your best sourcing signals), and what condition the overall market is searching for right now. All endpoints on this page require the `demand-intent.read` scope and a valid `Authorization: Bearer <token>` header.

## Search demand vs. game demand

Search demand is keyed by **free-text query** rather than game ID. A single query like "chrono trigger" can span multiple titles and consoles depending on what inventory is listed. This means search data tells you what buyers are *typing*, while game demand tells you what they are *clicking* — the two signals are complementary. Because search rows are query-keyed, they cannot be filtered by `game_id`; use `console_id` or the [game demand endpoints](/api/demand-games) for game-level analysis.

Each search query unions two upstream sources: **price lookups** (buyers checking what a game is worth) and **site searches** (buyers browsing the catalog). Both are reflected in the combined `search_count`.

## Search demand score

The search `demand_score` is a 0–100 index blending volume and reach into one comparable number. Volume (combined search count) is the primary signal; reach (distinct users) is the secondary signal. There is no watch component — searches are not the same as notification alerts. The top-ranked query in the result set always scores 100.

## Leaderboard row shape

All search list endpoints return rows in this shape:

<ResponseField name="rank" type="integer">
  Precomputed rank by combined search volume within the period.
</ResponseField>

<ResponseField name="query" type="string">
  The normalized free-text query string.
</ResponseField>

<ResponseField name="search" type="object">
  Search volume and reach metrics.

  <ResponseField name="search_count" type="integer">Total searches (price lookups + site searches) in the period.</ResponseField>
  <ResponseField name="pricing_count" type="integer">Searches originating from price lookup flows.</ResponseField>
  <ResponseField name="site_search_count" type="integer">Searches originating from the site search interface.</ResponseField>
  <ResponseField name="distinct_users" type="integer">Number of unique users who searched this query.</ResponseField>
  <ResponseField name="mobile_share" type="float">Fraction of searches from mobile devices (0.0–1.0).</ResponseField>
</ResponseField>

<ResponseField name="results" type="object">
  Inventory availability signals for this query.

  <ResponseField name="avg_result_count" type="float">Average number of results returned per search of this query.</ResponseField>
  <ResponseField name="zero_result_count" type="integer">Number of times this query returned zero results.</ResponseField>
  <ResponseField name="zero_result_share" type="float">Fraction of searches for this query that returned zero results (0.0–1.0).</ResponseField>
</ResponseField>

<ResponseField name="momentum" type="object">
  <ResponseField name="value" type="float">Momentum ratio (7-day search pace vs. 30-day baseline). `null` if no baseline.</ResponseField>
  <ResponseField name="label" type="string">`rising`, `steady`, `cooling`, or `unknown`.</ResponseField>
</ResponseField>

<ResponseField name="demand_score" type="integer">
  Composite 0–100 search demand index.
</ResponseField>

## Common query parameters

All list endpoints on this page share the following 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 searches associated with 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.
</ParamField>

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

***

## GET /api/v1/demand-intent/searches

Returns a ranked leaderboard of search queries by volume for the selected period. Use this to understand what buyers are actively searching and pricing, even before they click through to a listing.

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

### Query parameters

In addition to the [common parameters](#common-query-parameters):

<ParamField query="sort" type="string" default="volume">
  Sort order for the leaderboard. One of:

  * `volume` — by combined search count (default)
  * `momentum` — by the 7d-vs-30d search pace, fastest-rising first
  * `unmet` — by `zero_result_share` descending, then volume; restricted to queries meeting a minimum search threshold to filter out one-off typos
</ParamField>

### Response

Returns a paginated array of search leaderboard rows (see [Leaderboard row shape](#leaderboard-row-shape)). The `meta` object includes the resolved `period`, `period_date`, and `sort`.

**Example response:**

```json theme={null}
{
  "data": [
    {
      "rank": 1,
      "query": "chrono trigger",
      "search": {
        "search_count": 1240,
        "pricing_count": 820,
        "site_search_count": 420,
        "distinct_users": 890,
        "mobile_share": 0.44
      },
      "results": {
        "avg_result_count": 12.4,
        "zero_result_count": 38,
        "zero_result_share": 0.031
      },
      "momentum": { "value": 1.3, "label": "rising" },
      "demand_score": 100
    }
  ],
  "meta": {
    "period": "7d",
    "period_date": "2026-06-16",
    "sort": "volume",
    "pagination": { "mode": "page", "page": 1, "per_page": 25, "total": 3100, "last_page": 124 }
  },
  "links": { "next": "https://api.8bitedge.com/api/v1/demand-intent/searches?page=2", "prev": null }
}
```

***

## GET /api/v1/demand-intent/searches/trending

Returns rising search queries — the ones whose recent daily search pace most exceeds their 30-day baseline. The sort is fixed to `momentum` and cannot be overridden. Use this endpoint to get ahead of emerging demand before it shows up in the main volume leaderboard.

```bash theme={null}
curl -s "https://api.8bitedge.com/api/v1/demand-intent/searches/trending?period=7d" \
  -H "Authorization: Bearer $TOKEN" | jq
```

### 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 to searches associated with this console.
</ParamField>

<ParamField query="date" type="string">
  Override the target date (defaults to latest computed).
</ParamField>

<ParamField query="limit" type="integer" default="25">
  Page size.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor token for cursor-mode pagination.
</ParamField>

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

### Response

Returns a paginated array of search leaderboard rows in the same shape as `GET /api/v1/demand-intent/searches`. The `meta.sort` field is always `"momentum"`.

<Note>
  Queries with no 30-day baseline are excluded from this endpoint because momentum requires a prior period to compare against.
</Note>

***

## GET /api/v1/demand-intent/searches/unmet

Returns high-volume search queries that are consistently returning little or no inventory — your clearest supply-gap and sourcing signal. If buyers are repeatedly searching for a title and coming up empty, that is a direct opportunity to list it. The sort is fixed to `unmet` (highest `zero_result_share` first, then by volume) and cannot be overridden.

```bash theme={null}
curl -s "https://api.8bitedge.com/api/v1/demand-intent/searches/unmet?period=7d" \
  -H "Authorization: Bearer $TOKEN" | jq
```

### 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 to searches associated with this console.
</ParamField>

<ParamField query="date" type="string">
  Override the target date (defaults to latest computed).
</ParamField>

<ParamField query="limit" type="integer" default="25">
  Page size.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor token for cursor-mode pagination.
</ParamField>

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

### Response

Returns a paginated array of search leaderboard rows in the same shape as `GET /api/v1/demand-intent/searches`. Rows are sorted by `zero_result_share` descending, then by `search_count`. The `meta.sort` field is always `"unmet"`.

<Note>
  Results are restricted to queries that meet a minimum search-count threshold. This filters out one-off typos or rare queries that happen to return no results — the list reflects genuine, repeated, unmet demand.
</Note>

<Tip>
  Cross-reference the top queries here with the [game demand leaderboard](/api/demand-games) filtered by the same `console_id` to identify which specific games to source. A query with high `zero_result_share` combined with high `demand_score` on the matching game is a strong buy signal.
</Tip>

***

## GET /api/v1/demand-intent/searches/conditions

Returns the market-wide condition mix from active searches — showing what condition (loose, CIB, new, or any) buyers are explicitly searching for across the entire catalog. Use this to understand the overall market preference for condition before deciding how to grade and list your inventory.

This endpoint returns a `collection` (not a paginated list) of all four condition rows for the selected period.

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

### Query parameters

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

<ParamField query="date" type="string">
  Override the target date (defaults to latest computed).
</ParamField>

<Note>
  This endpoint does not accept a `game_id` filter — search rows are keyed by free-text query and carry no game ID. For a per-game condition breakdown, use [`GET /api/v1/demand-intent/games/{game_id}/conditions`](/api/demand-games#get-apiv1demand-intentgamesgame_idconditions) instead.
</Note>

### Response

<ResponseField name="data" type="array">
  All four condition rows, sorted by rank (search volume descending). The rows sum to approximately 1.0 on `condition_share`.

  <ResponseField name="rank" type="integer">Rank within the four conditions for the period.</ResponseField>
  <ResponseField name="condition" type="string">One of `loose`, `cib`, `new`, or `any`.</ResponseField>
  <ResponseField name="search_count" type="integer">Total condition-classified searches in the period for this condition.</ResponseField>
  <ResponseField name="condition_share" type="float">This condition's share of all condition-classified searches (0.0–1.0). All four rows sum to \~1.0.</ResponseField>
  <ResponseField name="distinct_users" type="integer">Unique users who searched with this condition in the period.</ResponseField>
  <ResponseField name="mobile_share" type="float">Fraction of searches from mobile devices (0.0–1.0).</ResponseField>
</ResponseField>

<ResponseField name="meta" type="object">
  <ResponseField name="period" type="string">The resolved period.</ResponseField>
  <ResponseField name="period_date" type="string">The date the data was computed for (YYYY-MM-DD).</ResponseField>
</ResponseField>

All four conditions are always returned. A condition with no search activity in the period appears as a zeroed row ranked after the active conditions.

**Example response:**

```json theme={null}
{
  "data": [
    { "rank": 1, "condition": "loose", "search_count": 4200, "condition_share": 0.52, "distinct_users": 3100, "mobile_share": 0.41 },
    { "rank": 2, "condition": "cib",   "search_count": 2400, "condition_share": 0.30, "distinct_users": 1800, "mobile_share": 0.39 },
    { "rank": 3, "condition": "new",   "search_count": 900,  "condition_share": 0.11, "distinct_users": 680,  "mobile_share": 0.35 },
    { "rank": 4, "condition": "any",   "search_count": 560,  "condition_share": 0.07, "distinct_users": 420,  "mobile_share": 0.43 }
  ],
  "meta": { "period": "7d", "period_date": "2026-06-16" }
}
```