Skip to content
Docs
APISign inStart free

Get the research schedule

The knowledge.research.get operation: GET /api/v1/tax/knowledge/research in the REST API and the knowledge_research_get tool in the MCP server.

GET/api/v1/tax/knowledge/research

Returns the research plan of the Jurisdiction Knowledge Base and what is due today (UTC): the research waves of waves.yaml with their status (merged once the wave's pull request is merged), dependency state and report; the recurring waves (rate sweeps, quarterly Tier 1 re-research, overdue reviews) with their current occurrence and whether it is due; the jurisdictions with records past nextReviewBy (overdue); and the wave reports. Each due item has a prompt to paste into a Claude Code session opened in the Ownrecord repository: research runs there, never in the platform (spec §42.6).

Waves and reports come from the research data compiled with the app (artifact); overdue records and wave scopes from the knowledge loaded in the database (loaded). Demand-based promotions need the demand index and aren't evaluated yet. Platform staff only.

At a glance

  • REST: GET /api/v1/tax/knowledge/research
  • MCP tool: knowledge_research_get
  • Operation ID: knowledge.research.get
  • 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: M3

Request

Query parameters

This operation takes no query parameters.

Response

200 OK with a JSON object:

FieldTypeDescription
object"knowledge_research"
todaystring
artifactobject
artifact.availableboolean
artifact.commitstring or null
artifact.problemstring or null
loadedobject or null
wavesarray of object
waves[].idstring
waves[].kindone of research, review
waves[].statusone of planned, merged
waves[].whenstring or null
waves[].stateone of merged, ready, blocked
waves[].dependenciesarray of object
waves[].dependencies[].idstring
waves[].dependencies[].statusone of planned, merged, unknown
waves[].runsinteger (at least 0)
waves[].jurisdictionsinteger (at least 0)
waves[].foldersPresentinteger (at least 0)
waves[].doneinteger (at least 0)
waves[].branchstring
waves[].reportobject or null
waves[].promptstring
recurringarray of object
recurring[].idstring
recurring[].kindone of research_diff, plan
recurring[].schedulearray of string or one of weekly, monthly, quarterly
recurring[].scheduleLabelstring
recurring[].scopeobject or null
recurring[].occurrencestring
recurring[].nextstring
recurring[].dueboolean
recurring[].evaluatedboolean
recurring[].reasonstring
recurring[].inScopearray of string
recurring[].reportobject
recurring[].report.filestring
recurring[].report.existsboolean
recurring[].promptstring
overduearray of object
overdue[].jurisdictionIdstring
overdue[].namestring or null
overdue[].tier1 or 2 or 3 or null
overdue[].earlieststring
overdue[].recordsarray of object
overdue[].records[].refstring
overdue[].records[].nextReviewBystring
overdue[].records[].statusone of researched, cross_checked, reviewed, verified, retired
overdue[].promptstring
reportsarray of object
reports[].idstring
reports[].titlestring

Examples

A quarterly Tier 1 re-research is due

HTTP
GET /api/v1/tax/knowledge/research
Authorization: Bearer or_test_…

Response (200):

JSON
{
  "object": "knowledge_research",
  "today": "2026-10-13",
  "artifact": {
    "available": true,
    "commit": "1c14b2ec912aca347dd518b2044096f3b5d8eef1",
    "problem": null
  },
  "loaded": {
    "root": "knowledge",
    "commit": "1c14b2ec912aca347dd518b2044096f3b5d8eef1"
  },
  "waves": [
    {
      "id": "t1-w2-eu-members",
      "kind": "research",
      "status": "merged",
      "when": "development M2",
      "state": "merged",
      "dependencies": [
        {
          "id": "t1-w1-foundations",
          "status": "merged"
        }
      ],
      "runs": 4,
      "jurisdictions": 27,
      "foldersPresent": 27,
      "done": 27,
      "branch": "knowledge/t1-w2-eu-members",
      "report": {
        "id": "t1-w2-eu-members",
        "title": "Wave report — t1-w2-eu-members"
      },
      "prompt": "Run research wave `t1-w2-eu-members` per spec §42.6"
    },
    {
      "id": "t1-w3-crosscheck",
      "kind": "review",
      "status": "planned",
      "when": "development M2–M3",
      "state": "ready",
      "dependencies": [
        {
          "id": "t1-w2-eu-members",
          "status": "merged"
        }
      ],
      "runs": 82,
      "jurisdictions": 82,
      "foldersPresent": 82,
      "done": 12,
      "branch": "knowledge/t1-w3-crosscheck",
      "report": null,
      "prompt": "Run research wave `t1-w3-crosscheck` per spec §42.6"
    }
  ],
  "recurring": [
    {
      "id": "tier1-quarterly",
      "kind": "research_diff",
      "schedule": "quarterly",
      "scheduleLabel": "Quarterly",
      "scope": {
        "tiers": [1]
      },
      "occurrence": "2026-10-01",
      "next": "2027-01-01",
      "due": true,
      "evaluated": true,
      "reason": "31 jurisdictions in scope.",
      "inScope": ["AT", "BE", "HR"],
      "report": {
        "file": "reports/tier1-quarterly-2026-10-01.md",
        "exists": false
      },
      "prompt": "Run research wave `tier1-quarterly` per spec §42.6 (occurrence 2026-10-01). `pnpm knowledge:wave plan tier1-quarterly --today 2026-10-13` lists its runs and prompts; the wave report goes to data/tax/knowledge/reports/tier1-quarterly-2026-10-01.md."
    }
  ],
  "overdue": [],
  "reports": [
    {
      "id": "t1-w2-eu-members",
      "title": "Wave report — t1-w2-eu-members"
    }
  ]
}

Errors

CodeHTTP statusWhenWhat to do
permission_denied403You aren't platform staff (organizations read the knowledge itself, not the research schedule).Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: validation_failed, api_version_unsupported, authentication_required, api_key_invalid, resource_not_found, dry_run_not_supported, rate_limited, internal_error.