> ## 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.
# Use intelligence scores to decide what to buy, hold, and how to list
> Learn how to use the 8bitedge Intelligence API to rank titles by liquidity, profile a single game, choose the right listing condition, and score a whole lot or inventory.
The 8bitedge Intelligence API takes the raw demand signals you read in the [Demand & Intent](/guides/demand-signals) guide and blends them with catalog pricing to answer the decisions a seller actually makes: *what should I buy, what will sit, and how should I list it?* Where demand endpoints **report** behavior, intelligence endpoints **score and recommend** — collapsing demand, momentum, and price into a single `liquidity_score` and, for a copy in hand, a recommended condition. This guide maps each endpoint to a concrete seller question.
All intelligence endpoints require the **`intelligence.read`** scope on your API key. Requests with a key missing this scope receive `403 insufficient_scope`.
**Liquidity is a turnover proxy, not a measured sell-through rate.** `liquidity_score` blends a *demand component* (first-party intent, reach, and watch demand) with a *price component* (catalog pricing). Supply is not directly observed, so treat the score as a relative ranking signal — "this should move more readily than that" — rather than a guaranteed sale rate.
## How intelligence scoring works
Every intelligence response is built from two ingredients: a normalized **demand index** and a **price accessibility** score. Understanding them makes every endpoint on this page readable at a glance.
**Demand index** (`demand.index`) — a `0.0`–`1.0` blend of three demand signals: intent (redirect clicks), reach (distinct users), and watch demand (watchlist alerts). Each is normalized against the highest value in the current period and console scope, so the most-demanded title approaches `1.0` and every other title scores relative to it.
**Price accessibility** (`price_accessibility`) — a `0.0`–`1.0` score that is *higher for cheaper titles*, on the principle that lower-priced games turn over faster:
```
price_accessibility = 1 − (price_complete ÷ max_complete_price_in_scope)
```
A title with no catalog price falls back to a neutral `0.5`, so missing pricing never masquerades as high liquidity.
**Liquidity score** (`liquidity_score`) — a single `0`–`100` index combining the two:
```
liquidity_score = 100 × (w_demand · demand.index + w_access · price_accessibility)
```
The weights sum to 1 and are set in the API's serving configuration. A high score means a title is both in demand *and* priced to move.
**Momentum** — the same accelerating/fading signal used across Demand & Intent: the trailing 7-day daily pace against the 30-day baseline, labeled `rising` (1.2 or above), `steady` (0.8–1.2), or `cooling` (below 0.8). With no 30-day baseline, `value` is `null` and `label` is `unknown`.
***
## "Across the catalog, what will actually move?"
Use the **liquidity leaderboard** to rank titles by how readily they should move, weighing demand against price in one number.
```bash theme={null}
curl -s "https://api.8bitedge.com/api/v1/intelligence" \
-H "Authorization: Bearer $TOKEN" | jq
```
By default the endpoint returns the top titles for the last 7 days, sorted by `liquidity_score`. Each row looks like this:
```json theme={null}
{
"rank": 3,
"game": {
"id": 5337,
"name": "Super Mario World",
"slug": "super-mario-world",
"console_id": 19,
"console_name": "Nintendo SNES"
},
"demand": { "redirects": 412, "distinct_users": 287, "watch_count": 53, "index": 0.8123 },
"momentum": { "value": 1.34, "label": "rising" },
"pricing": { "loose": "28.00", "complete": "75.00", "new": "320.00" },
"price_accessibility": 0.7656,
"liquidity_score": 78
}
```
**Sorting options** — use `?sort=` to change how the leaderboard is ranked:
| Value | Ranks by | Best for |
| --------------------- | ----------------------------------------- | ---------------------------------------------------------- |
| `liquidity` (default) | `liquidity_score` descending | Finding what should turn over fastest, all factors weighed |
| `demand` | `demand.index` descending (ignores price) | Pure interest, regardless of how expensive the title is |
| `value` | Complete-in-box price descending | Highest-margin titles first; `liquidity_score` breaks ties |
```bash theme={null}
# Rank by demand only, ignoring price
curl -s "https://api.8bitedge.com/api/v1/intelligence?sort=demand" \
-H "Authorization: Bearer $TOKEN" | jq
# Rank by resale value (highest CIB price first)
curl -s "https://api.8bitedge.com/api/v1/intelligence?sort=value" \
-H "Authorization: Bearer $TOKEN" | jq
```
The three sorts answer different budgets. `liquidity` is for fast turnover, `value` is for margin per unit, and `demand` surfaces high-interest titles you might list at a premium even when they aren't "accessible" by price.
***
## "How liquid is this specific title, and why?"
Use the **game profile** endpoint to score a single title. Pass the game's numeric `id` (from a catalog lookup or leaderboard row) as the path parameter.
```bash theme={null}
curl -s "https://api.8bitedge.com/api/v1/intelligence/5337?period=7d" \
-H "Authorization: Bearer $TOKEN" | jq
```
The response is a single row in the same shape as a leaderboard entry — `demand`, `momentum`, `pricing`, `price_accessibility`, and `liquidity_score`. Unlike the leaderboard, which only includes titles that have redirect demand, the profile is anchored on the catalog: **any enabled game resolves, even one with zero demand**, and its score is normalized against the whole period population so it stays comparable to the leaderboard.
The endpoint returns `404 not_found` only when the ID isn't a real, enabled game. A valid title with no demand still returns a row — just with low metrics and a correspondingly low `liquidity_score`.
***
## "I have a copy — should I list it loose, CIB, or new?"
Use the **condition strategy** endpoint to turn a copy in hand into a listing decision. It blends where buyer demand concentrates with each condition's relative price, scores all three sellable conditions, and names a recommended one.
```bash theme={null}
curl -s "https://api.8bitedge.com/api/v1/intelligence/5337/conditions?period=7d" \
-H "Authorization: Bearer $TOKEN" | jq
```
```json theme={null}
{
"data": {
"game": { "id": 5337, "name": "Super Mario World", "slug": "super-mario-world", "console_id": 19, "console_name": "Nintendo SNES" },
"pricing": { "loose": "28.00", "complete": "75.00", "new": "320.00" },
"premiums": { "complete_over_loose": 1.6786, "new_over_complete": 3.2667 },
"conditions": [
{ "condition": "loose", "price": "28.00", "watch_count": 12, "demand_share": 0.30, "value_index": 0.0875, "strategy_score": 34 },
{ "condition": "cib", "price": "75.00", "watch_count": 28, "demand_share": 0.55, "value_index": 0.2344, "strategy_score": 71 },
{ "condition": "new", "price": "320.00", "watch_count": 3, "demand_share": 0.06, "value_index": 1.0, "strategy_score": 52 }
],
"recommended": { "condition": "cib", "reason": "where buyer demand concentrates" }
},
"meta": { "period": "7d", "period_date": "2026-06-19" }
}
```
Read each condition row as a trade-off between two normalized signals:
* **`demand_share`** — this condition's slice of the title's watch demand. In the example, 55% of alerts for Super Mario World want it CIB.
* **`value_index`** — this condition's price relative to the title's priciest condition (`new` is `1.0` here).
* **`strategy_score`** — the `0`–`100` blend of the two, ranked across the three conditions.
The `recommended` block names the highest-scoring condition and explains *why* against the pure-demand and pure-value winners — here CIB wins because demand concentrates there, even though a sealed copy carries the highest price. The `premiums` ratios tell you what each upgrade is worth: `complete_over_loose: 1.6786` means CIB sells for about 168% of the loose price.
This endpoint *recommends*. To see the raw per-condition demand breakdown across all four conditions (including `any`) without the scoring layer, use the Demand & Intent endpoint [`/demand-intent/games/{id}/conditions`](/api/demand-conditions).
***
## "Here's my pile — score every title for me"
Use the **batch** endpoint to score a whole lot or inventory in one request. Submit a list of game IDs and each is scored with the same liquidity logic as the leaderboard, against one shared period scope resolved once for the batch.
```bash theme={null}
curl -s -X POST "https://api.8bitedge.com/api/v1/intelligence/batch?period=7d" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "requests": [ { "game_id": 5337 }, { "game_id": 412 }, { "game_id": 999999 } ] }' | jq
```
Each item returns its own status and liquidity row, alongside an aggregate `meta.batch` summary. Unknown IDs don't fail the batch — they come back as `{ "found": false }`:
```json theme={null}
{
"data": [
{ "status": 200, "data": { "game": { "id": 5337, "name": "Super Mario World", "...": "..." }, "liquidity_score": 78 } },
{ "status": 200, "data": { "game": { "id": 412, "name": "Chrono Trigger", "...": "..." }, "liquidity_score": 64 } },
{ "status": 200, "data": { "game_id": 999999, "found": false } }
],
"meta": { "batch": { "total": 3, "succeeded": 3, "failed": 0 } }
}
```
You get a `200` when every item succeeds and a `207` when there's a mix — always inspect each item's `status`. Each object in `requests` counts as **one usage unit**, whether it succeeds, fails, or resolves to `found: false`, and the batch is capped at your plan's `max_batch_size`.
For retry-safe batches, send an `Idempotency-Key` header — a repeat with the same key and identical payload replays the original response verbatim. See the [Batch requests](/guides/batch-requests) guide for the full pattern.
***
## Filtering by console
The leaderboard accepts a `?console_id=` parameter to focus scoring on a single platform — useful when you specialize in one system. Because `price_accessibility` and `demand.index` are normalized within scope, filtering to a console re-bases the scores against that console's own range rather than the whole catalog.
```bash theme={null}
# Top SNES titles (console_id 19) by liquidity
curl -s "https://api.8bitedge.com/api/v1/intelligence?console_id=19" \
-H "Authorization: Bearer $TOKEN" | jq
```
Use the [`/consoles`](/api/consoles) endpoint to look up valid console IDs.
***
## Period and date parameters
Every intelligence endpoint accepts the same two time-control parameters:
| Parameter | Values | Default | Notes |
| --------- | ------------------ | --------------- | ---------------------------- |
| `period` | `day`, `7d`, `30d` | `7d` | Time window for the metrics |
| `date` | ISO date string | Latest computed | Override the window-end date |
The response `meta` includes the resolved `period` and `period_date` (and `sort` on the leaderboard) so you can confirm which window your scores reflect. On the batch endpoint, both parameters are applied once to the whole batch.
***
## Next steps
Full reference for the liquidity leaderboard, per-game profile, and batch scoring.
Full reference for the condition strategy endpoint and its scoring fields.
The first-party demand data that feeds every intelligence score.
Patterns for batching and idempotent, retry-safe requests.