# List tax rates > The knowledge.rates.list operation: GET /api/v1/tax/knowledge/rates in the REST API and the knowledge_rates_list tool in the MCP server. Lists the tax rates of the Jurisdiction Knowledge Base as loaded: per jurisdiction and tax category (`*` is the rate for every category without its own), with `kind`, `ratePpm` (parts per million as a string: "250000" is 25%), validity dates and the record `meta`: status, confidence, open questions, review dates and the file and commit it came from. `sources` are the sources the rate cites. Filter by `jurisdictionId`, `taxCategoryId` (`*` included) or `status` (one or several). Sorted by `key`; paginate with `limit` (1–100, default 50) and `starting_after` (the `next_cursor` of the previous page). Live mode uses only reviewed or verified rates, verified for Tier 1 (spec §7.2). ## At a glance - **REST:** `GET /api/v1/tax/knowledge/rates` - **MCP tool:** `knowledge_rates_list` - **Operation ID:** `knowledge.rates.list` - **Scope:** Platform - **Permission:** `tax_knowledge:read` - **Risk tier:** `read` - **Dry run:** Not supported - **Idempotency:** Not needed (read only) - **Modes:** Test and live - **Pagination:** `limit` (at most 100) and `starting_after` - **Authentication:** API key with the `tax_knowledge:read` scope - **Since:** M3 ## Request ### Query parameters | Field | Type | Required | Description | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------- | | `jurisdictionId` | string | No | | | `taxCategoryId` | string | No | | | `status` | one of `researched`, `cross_checked`, `reviewed`, `verified`, `retired` or array of one of `researched`, `cross_checked`, `reviewed`, `verified`, `retired` | No | | | `limit` | integer (1 to 100) | No | | | `starting_after` | string | No | | ## Response `200 OK` with a JSON object, a page of the list (newest first): | Field | Type | Description | | -------------------------------------- | ----------------------------------------------------------------------------------------- | ----------- | | `object` | `"list"` | | | `data` | array of object | | | `data[].id` | string | | | `data[].object` | `"tax_rate"` | | | `data[].key` | string | | | `data[].jurisdictionId` | string | | | `data[].taxCategoryId` | string | | | `data[].kind` | one of `standard`, `reduced`, `super_reduced`, `parking`, `zero`, `exempt`, `not_taxable` | | | `data[].ratePpm` | integer string | | | `data[].validFrom` | string | | | `data[].validTo` | string | | | `data[].conditions` | string | | | `data[].subdivision` | string | | | `data[].meta` | object | | | `data[].meta.status` | one of `researched`, `cross_checked`, `reviewed`, `verified`, `retired` | | | `data[].meta.fixture` | boolean | | | `data[].meta.confidence` | one of `high`, `medium`, `low` | | | `data[].meta.sourceIds` | array of string | | | `data[].meta.openQuestions` | integer (at least 0) | | | `data[].meta.unsupportedRules` | integer (at least 0) | | | `data[].meta.blockingUnsupportedRules` | integer (at least 0) | | | `data[].meta.reviewedBy` | string | | | `data[].meta.reviewedAt` | string | | | `data[].meta.verifiedBy` | string | | | `data[].meta.verifiedAt` | string | | | `data[].meta.nextReviewBy` | string | | | `data[].meta.knowledgeRef` | object | | | `data[].meta.knowledgeRef.path` | string | | | `data[].meta.knowledgeRef.commit` | string | | | `data[].sources` | array of object | | | `data[].sources[].id` | string | | | `data[].sources[].url` | string | | | `data[].sources[].title` | string | | | `data[].sources[].publisher` | string | | | `data[].sources[].type` | string | | | `data[].sources[].retrievedAt` | string | | | `data[].sources[].monitor` | boolean | | | `has_more` | boolean | | | `next_cursor` | string or null | | ## Examples ### Croatia's rates ```http GET /api/v1/tax/knowledge/rates?jurisdictionId=HR Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "id": "kn_01m4ttwd3veh9apbewxheq5xhb", "object": "tax_rate", "key": "HR/rates.yaml#*:standard@2013-01-01", "jurisdictionId": "HR", "taxCategoryId": "*", "kind": "standard", "ratePpm": "250000", "validFrom": "2013-01-01", "meta": { "status": "reviewed", "fixture": false, "confidence": "high", "sourceIds": ["HR:S1", "HR:S4"], "openQuestions": 0, "unsupportedRules": 0, "blockingUnsupportedRules": 0, "reviewedBy": "Ana Horvat", "reviewedAt": "2026-10-10", "nextReviewBy": "2027-04-13", "knowledgeRef": { "path": "data/tax/knowledge/jurisdictions/HR/rates.yaml", "commit": "1c14b2ec912aca347dd518b2044096f3b5d8eef1" } }, "sources": [ { "id": "HR:S1", "url": "https://narodne-novine.nn.hr/clanci/sluzbeni/2013_06_73_1451.html", "title": "Value Added Tax Act (Zakon o porezu na dodanu vrijednost)", "publisher": "Narodne novine", "type": "law", "retrievedAt": "2026-10-13", "monitor": true } ] } ], "has_more": false, "next_cursor": null } ``` ### Rates not reviewed yet, two per page ```http GET /api/v1/tax/knowledge/rates?status=researched&status=cross_checked&limit=2 Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "id": "kn_01m4ttwd3veh9apbewxheq5xhg", "object": "tax_rate", "key": "AT/rates.yaml#*:standard@2016-01-01", "jurisdictionId": "AT", "taxCategoryId": "*", "kind": "standard", "ratePpm": "200000", "validFrom": "2016-01-01", "meta": { "status": "cross_checked", "fixture": false, "confidence": "high", "sourceIds": [], "openQuestions": 0, "unsupportedRules": 0, "blockingUnsupportedRules": 0, "reviewedBy": "Ana Horvat", "reviewedAt": "2026-10-10", "nextReviewBy": "2027-04-13", "knowledgeRef": { "path": "data/tax/knowledge/jurisdictions/HR/rates.yaml", "commit": "1c14b2ec912aca347dd518b2044096f3b5d8eef1" } }, "sources": [] } ], "has_more": true, "next_cursor": "AT/rates.yaml#*:standard@2016-01-01" } ``` ## Errors | Code | HTTP status | When | What to do | | -------------------------------------------------------------------------------------- | ----------- | ------------------------------------------ | ------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A filter or the page size 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 | Your credentials can't read tax knowledge. | 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).