Reports

Free shelf and report menu; paid All and Range return IntelReportSnapshot bodies only.

Reports

Audience: agents and integrators.
API base: see Environments.

Agents get shared reports only. Profile, posts, and edges are never returned from these routes.

Free shelf — GET /api/intel/list

Lists handles (and light index metadata) that have shared library data on this deployment.

Auth	None
Cache	Short shared cache when configured
Empty KV	{ "configured": false, "entries": [] }

Free menu — GET /api/intel/reports?username=

Query:

Param	Required	Notes
username	Yes	Handle without requiring @

Response: { username, reportCount, reports: ReportMenuItem[] } where each item is:

Field	Type
id	string
createdAt	ISO string
model	string
postCount	number
dateRange	{ from, to } | null

Use this to decide All vs Range before paying.

Paid All — select=all

GET /api/intel/reports?username={user}&select=all

Returns every report in that handle’s shared history (after payment or library secret).

Paid Range — select=range

GET /api/intel/reports?username={user}&select=range&from=&to=
GET /api/intel/reports?username={user}&select=range&ids=id1,id2

Param	Required	Notes
select	range
from / to	At least one of from, to, or ids	Compared against createdAt as strings
ids	Optional	Comma-separated report ids

• Missing filters → 400 range_requires_from_to_or_ids
• No matches → 404 no_matching_reports
• Charge = unit price × number of matched reports

Paid success body

{
  "username": "AskVenice",
  "select": "all",
  "reportCount": 2,
  "chargedUsd": 0.02,
  "reports": [ /* IntelReportSnapshot */ ]
}

(chargedUsd appears on agent-paid responses.)

IntelReportSnapshot (summary)

Each report includes roughly:

• id, createdAt, model, synthesisSettings
• meta — postCount, dateRange, postIdsAnalyzed, token fields, optional includedReportIds
• analytics — structured metrics snapshot
• narrative — AI narrative sections
• changeSummary — null on the baseline report; otherwise delta vs prior
• previousReportId

Exact nested shapes evolve with the app; treat unknown fields as forward-compatible.

Not in this product

Endpoint	Role
GET/PUT /api/intel/bundle	Full dossier — library secret only (first-party)
Venice proxy / X demo PAYG	Separate rails — not documented here yet

Related

• Auth and payment
• Errors
• Pricing