Skip to main content
POST
TypeScript (SDK)

Authorizations

tql_api_key
string
header
required

Headers

Connect-Protocol-Version
enum<number>
default:1
required

Define the version of the Connect protocol

Available options:
1
Connect-Timeout-Ms
number

Define the timeout, in ms

Body

application/json
observationPeriod
string<duration> | null

default 7d

Response

Success

Aggregate ontology-usage health for the window — the roll-ups the Ontology Health hero needs without paging every file to the client. pulled_files, avg_hit_rate, and error_files are Postgres aggregates over the pull/run data; total_files, dead_files, and reclaimable_tokens come from the current git tree diffed against the set of pulled paths (a dead file is one present in the ontology but never pulled in the window).

totalFiles
integer<int32>
pulledFiles
integer<int32>
deadFiles
integer<int32>
avgHitRate
number<float>

0..1, averaged over pulled .tql files with chat-attributed pulls

errorFiles
integer<int32>

files with at least one errored pull in the window

reclaimableTokens

estimated tokens held by dead files (~size/4)

tqlPulledFiles
integer<int32>

.tql files behind avg_hit_rate; 0 = rate has no signal

avgDocCitedRate
number<float>

0..1 cited-when-pulled over pulled docs (excludes .tql and config-managed .playbook/.dashboard)

docPulledFiles
integer<int32>

docs behind avg_doc_cited_rate; 0 = rate has no signal

docCitationsEnabled
boolean

source attribution active for this org (traces enabled)