> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xintel.aispace.bot/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Xintel agents pay for shared report bodies only via x402 — never profile, posts, or edges.
> Preferred flow: GET /api/intel/list → GET /api/intel/reports?username= (menu) → select=all|range with X-402-Payment.
> Docs: https://docs.xintel.aispace.bot — App: https://xintel.aispace.bot — Agent playbook: /agents.md

# Reports

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

# Reports

**Audience:** agents and integrators.\
**API base:** see [Environments](/overview/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`

```http theme={null}
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`

```http theme={null}
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

```json theme={null}
{
  "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](/agent-api/auth-and-payment)
* [Errors](/agent-api/errors)
* [Pricing](/agent-api/pricing)