Tether
DocsGitHub

API reference

Insights

Chat answers a question. Insights answers the question nobody asked: what should someone looking at this scope notice today?

POST /v1/insights

Request

curl -X POST https://api.trytether.ge/v1/insights \
  -H "X-Api-Key: $TETHER_SECRET_KEY" \
  -H "X-Tether-Scope-Id: 9" \
  -H "Content-Type: application/json" \
  -d '{ "daysBack": 30, "maxItems": 20 }'
FieldTypeDefaultNotes
daysBackinteger30Analysis window, ending now. Also sets meta.time_range.
maxItemsinteger20Upper bound on rows the analysis considers per section.
promptstring—Optional steer: "focus on cost" rather than a free-form question.
includeContextbooleantrueWhether pre-turn context assembly runs.
organizationId, locationIdinteger—Ignored. Scope comes from the credential.

Response

The same document as /v1/chat — same content_type, same block types, same validation and repair path.

{
  "content_type": "application/vnd.tether.blocks.v1+json",
  "version": "tether.blocks.v1",
  "title": "Last 30 days",
  "blocks": [
    { "type": "kpi", "id": "headline", "items": [
      { "label": "Spend", "value": 41280, "delta": 0.12, "intent": "negative" },
      { "label": "Orders", "value": 1184, "delta": 0.03, "intent": "positive" }
    ] },
    { "type": "ranked_list", "id": "movers", "title": "Biggest movers",
      "rows": [{ "label": "Produce", "value": 3120, "trend": "up" }] },
    { "type": "text", "id": "note", "variant": "body",
      "markdown": "Produce spend rose 31% against a 3% increase in orders." }
  ],
  "meta": { "time_range": { "start": "2026-07-21T00:00:00Z", "end": "2026-08-20T00:00:00Z" } }
}

Two differences from a chat response worth knowing:

  • There is no session_id. An insights call is not a conversation and does not continue one.
  • pending_actions is not populated. Insights does not stage writes — an unprompted analysis is the wrong place to propose a mutation nobody asked for.

What it is for

Dashboard panels. A block of analysis on a page someone already looks at every morning.

Scheduled digests. Call it on a cron, render the blocks into email or a chat message.

Onboarding. A new user opening an empty product surface gets something to react to.

Because the response is the same typed contract as chat, the renderer you already wrote for chat renders it unchanged.

Cost

An insights call is an ordinary billable turn against the same ledger, budget breaker and tier ceilings as chat. It is usually more expensive than a typical chat turn: the analysis window is wider and the answer is longer.

Two consequences worth planning for:

  • Do not call it per page view. Compute it on a schedule and cache the document; it describes a 30-day window, so it does not change between refreshes of a page.
  • It counts against the same caps. A nightly digest across every scope of every tenant can trip a daily budget ceiling that conversational traffic never came near. See Cost and quotas.

Scope

Insights is scoped exactly like chat: the tenant comes from the key, and X-Tether-Scope-Id narrows it. Omitting the scope header produces a tenant-wide analysis, which is meaningful for some domains and noise for others.

For a per-site digest, call once per site with the scope header set. The results are not comparable across scopes unless you asked for the same daysBack.