Research a question, reported as it happens

The same capability as POST /api/research, with progress. Not a second implementation: it runs the same pipeline, and the done event carries exactly what the other route returns.

The response is a server-sent event stream, so it is exempt from the usual {success, result, message} envelope. Each frame is an event: name and a data: payload holding one event object.

Events arrive in this order. started immediately, which exists only to prove the stream is open while the model plans, because that call alone can take ten seconds. planned with the sub-questions. One searched per sub-question, as each lands rather than all together at the end. sources with everything gathered so far. writing once the reading is done. Then delta fragments as the answer is generated, and finally done.

Treat everything before done as a view of the wait. The deltas are raw model output, and the finished answer has had any citation pointing at no source stripped out of it, so the two can differ. A client that rebuilt the report from fragments would also have no way to notice a dropped connection.

POST rather than GET because the question is a body, which the browser EventSource API cannot send. Read it with fetch and parse the frames.

POST

api

research

stream

Research a question, reported as it happens

curl --request POST \
  --url https://api.truscan.co/api/research/stream \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "question": "how do solid state batteries differ from lithium ion in practice",
  "depth": 2,
  "max_sources": 24,
  "lang": "<string>"
}
'

import requests

url = "https://api.truscan.co/api/research/stream"

payload = {
    "question": "how do solid state batteries differ from lithium ion in practice",
    "depth": 2,
    "max_sources": 24,
    "lang": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    question: 'how do solid state batteries differ from lithium ion in practice',
    depth: 2,
    max_sources: 24,
    lang: '<string>'
  })
};

fetch('https://api.truscan.co/api/research/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.truscan.co/api/research/stream"

	payload := strings.NewReader("{\n  \"question\": \"how do solid state batteries differ from lithium ion in practice\",\n  \"depth\": 2,\n  \"max_sources\": 24,\n  \"lang\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "type": "started",
  "round": 123,
  "questions": [
    {
      "round": 123,
      "question": "<string>",
      "query": "<string>",
      "found": 123
    }
  ],
  "step": {
    "round": 123,
    "question": "<string>",
    "query": "<string>",
    "found": 123
  },
  "sources": [
    {
      "index": 123,
      "url": "<string>",
      "title": "<string>",
      "domain": "<string>",
      "excerpt": "<string>",
      "published_at": "2023-11-07T05:31:56Z",
      "cited": true
    }
  ],
  "text": "<string>",
  "report": {
    "id": "rsch_8d3ddecc038c10d4",
    "question": "<string>",
    "answer": "<string>",
    "sources": [
      {
        "index": 123,
        "url": "<string>",
        "title": "<string>",
        "domain": "<string>",
        "excerpt": "<string>",
        "published_at": "2023-11-07T05:31:56Z",
        "cited": true
      }
    ],
    "steps": [
      {
        "round": 123,
        "question": "<string>",
        "query": "<string>",
        "found": 123
      }
    ],
    "stats": {
      "took_ms": 123,
      "rounds": 123,
      "searches": 123,
      "pages": 123,
      "model_calls": 123,
      "tokens": 123,
      "cached": true
    }
  },
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>",
  "result": {
    "code": "<string>"
  }
}

{
  "success": false,
  "message": "<string>",
  "result": {
    "code": "<string>"
  }
}

{
  "success": false,
  "message": "<string>",
  "result": {
    "code": "<string>"
  }
}

{
  "success": false,
  "message": "<string>",
  "result": {
    "code": "<string>"
  }
}

Authorizations

Authorization

string

header

required

An API key, sent as Authorization: Bearer enc_…. A dashboard session cookie works on the same route.

Body

application/json

question

string

required

What to research. query is accepted as an alias.

Maximum string length: 1000

Example:

"how do solid state batteries differ from lithium ion in practice"

depth

integer

default:2

Rounds of search-and-read. Round one searches what the question obviously needs; each round after asks what is still missing and searches for that. A round may end the report early by finding nothing missing, which is a correct answer rather than a shortcut.

Required range: 1 <= x <= 3

max_sources

integer

default:24

How many pages may be cited.

Required range: 1 <= x <= 24

freshness

enum<string>

Restricts every search behind the report.

Available options:

any,

day,

week,

month,

year

lang

string

Response

A server-sent event stream.

One frame of the stream. Which fields are present depends on type.

type

enum<string>

required

Available options:

started,

planned,

searched,

sources,

writing,

delta,

done,

error

round

integer

On planned and searched.

questions

object[]

On planned: the sub-questions this round will search.

Show child attributes

step

object

On searched: the sub-question that just finished.

Show child attributes

sources

object[]

On sources: everything gathered so far, renumbered.

Show child attributes

text

string

On delta: a fragment of the answer.

report

object

On done: the finished report. This one is the authority.

Show child attributes

message

string

On error: a sentence explaining why there will be no report.

Last modified on September 24, 2026

⌘I

Research a question, reported as it happens

curl --request POST \
  --url https://api.truscan.co/api/research/stream \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "question": "how do solid state batteries differ from lithium ion in practice",
  "depth": 2,
  "max_sources": 24,
  "lang": "<string>"
}
'

import requests

url = "https://api.truscan.co/api/research/stream"

payload = {
    "question": "how do solid state batteries differ from lithium ion in practice",
    "depth": 2,
    "max_sources": 24,
    "lang": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    question: 'how do solid state batteries differ from lithium ion in practice',
    depth: 2,
    max_sources: 24,
    lang: '<string>'
  })
};

fetch('https://api.truscan.co/api/research/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.truscan.co/api/research/stream"

	payload := strings.NewReader("{\n  \"question\": \"how do solid state batteries differ from lithium ion in practice\",\n  \"depth\": 2,\n  \"max_sources\": 24,\n  \"lang\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "type": "started",
  "round": 123,
  "questions": [
    {
      "round": 123,
      "question": "<string>",
      "query": "<string>",
      "found": 123
    }
  ],
  "step": {
    "round": 123,
    "question": "<string>",
    "query": "<string>",
    "found": 123
  },
  "sources": [
    {
      "index": 123,
      "url": "<string>",
      "title": "<string>",
      "domain": "<string>",
      "excerpt": "<string>",
      "published_at": "2023-11-07T05:31:56Z",
      "cited": true
    }
  ],
  "text": "<string>",
  "report": {
    "id": "rsch_8d3ddecc038c10d4",
    "question": "<string>",
    "answer": "<string>",
    "sources": [
      {
        "index": 123,
        "url": "<string>",
        "title": "<string>",
        "domain": "<string>",
        "excerpt": "<string>",
        "published_at": "2023-11-07T05:31:56Z",
        "cited": true
      }
    ],
    "steps": [
      {
        "round": 123,
        "question": "<string>",
        "query": "<string>",
        "found": 123
      }
    ],
    "stats": {
      "took_ms": 123,
      "rounds": 123,
      "searches": 123,
      "pages": 123,
      "model_calls": 123,
      "tokens": 123,
      "cached": true
    }
  },
  "message": "<string>"
}

{
  "success": false,
  "message": "<string>",
  "result": {
    "code": "<string>"
  }
}

{
  "success": false,
  "message": "<string>",
  "result": {
    "code": "<string>"
  }
}

{
  "success": false,
  "message": "<string>",
  "result": {
    "code": "<string>"
  }
}

{
  "success": false,
  "message": "<string>",
  "result": {
    "code": "<string>"
  }
}

Search

Extract

Answer

Research

Crawl

Webhooks

Request logs

API keys

Research a question, reported as it happens

Authorizations

Body

Response