# List the demand index > The knowledge.demand.list operation: GET /api/v1/tax/knowledge/demand in the REST API and the knowledge_demand_list tool in the MCP server. The demand index: per customer-location jurisdiction, the demand across every organization in one mode (spec §42.2, README §7). For each jurisdiction with a signal: waitlist entries by stage (`waiting`, `pending`, `notified`, `left`) with the waiting entries' estimated value; checkouts paused there in the window (`blockedCheckouts`, by reason); net sales in the window where the knowledge base is only at coverage L0 (`l0Sales`, where quotes are out of scope, with an EUR equivalent for sorting); and subscribers' legal entities established there. With each, how many organizations and brands it comes from, never which: the index holds counts and sums only, no customer data. `coverage` is the jurisdiction's level, target and tier, to compare demand with what the knowledge base supports. Sort by `waitlist`, `blocked_checkouts`, `l0_sales`, `entities` or `jurisdiction`; the window is this calendar month and the ones before it (`months`, default 12). Platform staff only. ## At a glance - **REST:** `GET /api/v1/tax/knowledge/demand` - **MCP tool:** `knowledge_demand_list` - **Operation ID:** `knowledge.demand.list` - **Scope:** Platform - **Permission:** `tax_knowledge:read` - **Risk tier:** `read` - **Dry run:** Not supported - **Idempotency:** Not needed (read only) - **Modes:** Test and live - **Authentication:** API key with the `tax_knowledge:read` scope - **Since:** M7 ## Request ### Query parameters | Field | Type | Required | Description | | -------------- | ------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------- | | `mode` | one of `live`, `test` | No | Whose demand: live sales and waitlists (default), or test mode's. | | `months` | integer (1 to 36) | No | The window for blocked checkouts and L0 sales: this calendar month and the ones before it (1–36, default 12). | | `sort` | one of `jurisdiction`, `waitlist`, `blocked_checkouts`, `l0_sales`, `entities` | No | `waitlist` (waiting entries), `blocked_checkouts`, `l0_sales` (EUR equivalent), `entities` or `jurisdiction`. | | `order` | one of `asc`, `desc` | No | | | `jurisdiction` | string | No | Only this jurisdiction's row. | ## Response `200 OK` with a JSON object: | Field | Type | Description | | ---------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | | `object` | `"demand_index"` | | | `livemode` | boolean | | | `window` | object | Blocked checkouts and L0 sales are counted from `from` (a month's first day) to `to` (today, UTC). | | `window.months` | integer (at least 1) | | | `window.from` | string | | | `window.to` | string | | | `sort` | one of `jurisdiction`, `waitlist`, `blocked_checkouts`, `l0_sales`, `entities` | | | `order` | one of `asc`, `desc` | | | `fxRateDate` | string or null | The ECB publication used for `eurEquivalent`. | | `knowledgeCommit` | string or null | The loaded knowledge the coverage levels come from. | | `data` | array of object | | | `data[].jurisdiction` | string | The customer-location jurisdiction: `DE`, `US-TX`, a territory's code (`AX`) or an unknown country. | | `data[].name` | string or null | | | `data[].territoryOf` | string or null | For a territory: the jurisdiction whose VAT area it belongs to or borders. | | `data[].coverage` | object or null | The knowledge base's coverage; null when it has no jurisdiction record for the place. | | `data[].waitlist` | object | | | `data[].waitlist.waiting` | integer (at least 0) | Confirmed entries waiting for the brand to be able to sell. | | `data[].waitlist.pending` | integer (at least 0) | Entries whose email isn't confirmed yet. | | `data[].waitlist.notified` | integer (at least 0) | Entries told once that the brand can sell (the jurisdiction opened). | | `data[].waitlist.left` | integer (at least 0) | Entries whose customer left the waitlist. | | `data[].waitlist.organizations` | integer (at least 0) | | | `data[].waitlist.brands` | integer (at least 0) | | | `data[].waitlist.estimatedValue` | array of money | What the waiting entries wanted to buy, per currency. | | `data[].blockedCheckouts` | object | | | `data[].blockedCheckouts.total` | integer (at least 0) | Checkouts paused for a customer there in the window (once per session and reason). | | `data[].blockedCheckouts.registrationRequired` | integer (at least 0) | | | `data[].blockedCheckouts.jurisdictionBlocked` | integer (at least 0) | | | `data[].blockedCheckouts.other` | integer (at least 0) | Other reasons, e.g. unclear location evidence. | | `data[].blockedCheckouts.organizations` | integer (at least 0) | | | `data[].blockedCheckouts.brands` | integer (at least 0) | | | `data[].l0Sales` | object or null | Only for jurisdictions at coverage L0, where quotes are out of scope. | | `data[].establishedEntities` | object | | | `data[].establishedEntities.entities` | integer (at least 0) | Subscribers' legal entities established there (not archived). | | `data[].establishedEntities.organizations` | integer (at least 0) | | ## Examples ### Live demand over 12 months ```http GET /api/v1/tax/knowledge/demand Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "demand_index", "livemode": true, "window": { "months": 12, "from": "2025-11-01", "to": "2026-10-19" }, "sort": "waitlist", "order": "desc", "fxRateDate": "2026-10-16", "knowledgeCommit": "3c6925993d7a270b392e44860572530707616da4", "data": [ { "jurisdiction": "GB", "name": "United Kingdom", "territoryOf": null, "coverage": { "level": "L2", "target": "L3", "tier": 1 }, "waitlist": { "waiting": 42, "pending": 6, "notified": 0, "left": 2, "organizations": 5, "brands": 7, "estimatedValue": [ { "amount": "3150000000", "currency": "EUR" } ] }, "blockedCheckouts": { "total": 118, "registrationRequired": 112, "jurisdictionBlocked": 0, "other": 6, "organizations": 6, "brands": 9 }, "l0Sales": null, "establishedEntities": { "entities": 3, "organizations": 3 } }, { "jurisdiction": "KE", "name": "Kenya", "territoryOf": null, "coverage": { "level": "L0", "target": "L1", "tier": 3 }, "waitlist": { "waiting": 0, "pending": 0, "notified": 0, "left": 0, "organizations": 0, "brands": 0, "estimatedValue": [] }, "blockedCheckouts": { "total": 0, "registrationRequired": 0, "jurisdictionBlocked": 0, "other": 0, "organizations": 0, "brands": 0 }, "l0Sales": { "invoices": 214, "net": [ { "amount": "18400000000", "currency": "EUR" }, { "amount": "2500000000", "currency": "USD" } ], "organizations": 4, "eurEquivalent": { "amount": "20550000000", "currency": "EUR" } }, "establishedEntities": { "entities": 0, "organizations": 0 } } ] } ``` ## Errors | Code | HTTP status | When | What to do | | -------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A filter, the sort or the window is invalid. | Fix the fields listed in `details.issues` and send the request again. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You aren't platform staff (the index aggregates every organization's demand). | Ask an organization owner or admin for a role or scope that allows this action. | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).