---
name: research
description: Run deep, multi-source research queries via the kenkyu API and get back a cited answer with sources. Use for any question that benefits from a thorough, sourced investigation rather than a quick answer.
---

# kenkyu research API

kenkyu turns a natural-language research request into a plan, fans out parallel
searches (papers, web, twitter, reddit), filters and ranks the sources, and returns
a written answer plus the sources it drew from.

Base URL: `https://kenkyu.dev`. All endpoints are `POST` with a JSON body that
must include your `token`.

## POST /research

Body:

```json
{
  "token": "string",
  "query": "string — an opinionated natural-language research request; be specific about the sources or angle you care about",
  "time_limit_s": "int — seconds the run may spend, minimum 40; longer = more thorough; allow more than 180 for reasonable responses and more than 500 for a serious question that is pivotal to what the user is trying to do",
  "background": "bool, default false — false blocks until the run finishes and returns the full result; true returns {research_id} immediately, poll POST /check/research; prefer true for time_limit_s over ~60 so your HTTP call doesn't sit open"
}
```

Returns:

```json
{
  "research_id": "int",
  "query": "string — the request as run",
  "status": "complete | running | refused | failed",
  "answer": "string — the written research answer",
  "cost_usd": "float — what the run cost your balance",
  "elapsed_s": "float",
  "errors_parsing_source": "int — non-fatal source parse failures",
  "errors_executing_queries": "int — non-fatal subquery failures",
  "sources": [
    {
      "link": "string",
      "title": "string",
      "summary": "string — short summary of the source",
      "extract": "string — verbatim passages relevant to the query",
      "content": "string — full text when available",
      "weight": "high | medium | low — importance to the answer"
    }
  ]
}
```

Errors: `401` invalid token; `402` balance too low (`/research` requires a balance
above $10); `422` the planner refused the query (detail says why — rephrase and
retry); `404` the run failed (detail holds the error).

## POST /check/research

Body:

```json
{
  "token": "string",
  "research_id": "int — from a background: true research call"
}
```

Returns: while the run is in progress, `{research_id, query, status, error}` with
`status` `running | refused | failed`. Once `status` is `complete`, the same full
result shape as `/research`. Poll every few seconds until the status leaves
`running`.

## POST /user

Returns account info for the token, including `balance_usd`. Check it before
starting runs; below $10 `/research` is rejected.