---
title: "Reports API"
description: "Use when you read your personal value report over HTTP, page through its research sessions, or open and close the research sessions that the report is built from."
url: https://docs.heytrove.ai/reference/api/reports
updated: 2026-10-01
---

# Reports API

> Load this page when: you need the value report, or you need to record reads under a research session over HTTP

## For agents

- Open a session with POST /access/session, send its id in the X-CK-Session header on reads, and close it when done.
- Read the report with GET /reports/value and a since window such as 30d.
- Only you can read your own report.

The value report shows what your agents read. It is built from research sessions: a session is one research question, and the reads made under it. The CLI shows the same report with [trove value](https://docs.heytrove.ai/reference/cli/value.md).

## Get your value report

`GET https://heytrove.ai/api/v1/reports/value`

Returns your report for a time window. Only you can read it.

**Parameters**

| Name | In | Type | Required | Constraints | Meaning |
| --- | --- | --- | --- | --- | --- |
| `since` | query | string | no | `30d` style day count of 1 to 366, or `YYYY-MM-DD` | Start of the window. A day count looks back that many days. A date runs to today. |
| `from` | query | string | no | `YYYY-MM-DD` | Start date. Wins over `since`. |
| `to` | query | string | no | `YYYY-MM-DD` | End date. Wins over `since`. |
| `tz` | query | string | no | IANA time zone | Time zone for the window and the daily series. Default `UTC`. |
| `sessionsLimit` | query | integer | no | 0 to 100 | Sessions in the narrative. Default 25. |
| `sessionsOffset` | query | integer | no | 0 to 5,000 | Sessions to skip. |

With no window, the report covers the last 30 days.

**Request**

```bash
curl "https://heytrove.ai/api/v1/reports/value?since=30d&sessionsLimit=10" \
  -H "Authorization: Bearer trove_your_key"
```

**Response**

The top-level keys are listed here. Each one is an object or array with its own fields.

```json
{
  "window": { "from": "2026-09-02", "to": "2026-10-01", "tz": "UTC", "days": 30 },
  "totals": { "sessions": 12, "booksRead": 5, "pagesRead": 80, "contentReads": 20, "tocReads": 9, "untrackedReads": 2 },
  "outcomes": { "contentRead": 10, "tocOnly": 1, "noRead": 1, "hitRate": 0.83 },
  "sessions": { "sessions": [], "limit": 10, "offset": 0, "total": 12, "hasMore": true },
  "topSources": [],
  "daily": [],
  "funStats": { "equivalents": [], "headline": "…", "minutesOfReading": 120 },
  "deepestSession": null,
  "percentile": null,
  "busiestChannel": null,
  "wiki": null,
  "requestedBooks": null,
  "generatedAt": "2026-10-01T09:00:00.000Z"
}
```

`totals.pagesRead` counts only pages read through content reads. Table-of-contents reads are counted apart, in `tocReads`. Each session has `id`, `startedAt`, `intent`, `channel`, `client`, `outcome`, `bookCount`, `pagesRead` and `books`.

**Errors**

| Status | Message | Code | Fix |
| --- | --- | --- | --- |
| 400 | `Expected '<n>d' or 'YYYY-MM-DD', got: {value}` | none | Fix `since`. |
| 400 | `Expected YYYY-MM-DD, got: {value}` | none | Fix `from` or `to`. |
| 400 | `Invalid IANA timezone: {value}` | none | Use a name such as `Europe/Paris`. |
| 429 | `Rate limit exceeded` | `RATE_LIMITED` | Wait for `Retry-After`. |

**CLI equivalent**: [trove value](https://docs.heytrove.ai/reference/cli/value.md).

## List report sessions

`GET https://heytrove.ai/api/v1/reports/value/sessions`

Returns one page of the session narrative. It takes the same parameters as the report.

**Request**

```bash
curl "https://heytrove.ai/api/v1/reports/value/sessions?since=30d&sessionsLimit=25&sessionsOffset=25" \
  -H "Authorization: Bearer trove_your_key"
```

**Response**

```json
{
  "sessions": [
    {
      "id": "cmsess1",
      "startedAt": "2026-10-01T08:00:00.000Z",
      "intent": "retry strategy for flaky jobs",
      "channel": "cli",
      "client": "claude-code",
      "outcome": "content-read",
      "bookCount": 1,
      "pagesRead": 6,
      "books": [{ "itemId": "cmabc123", "title": "Use The Index, Luke", "depth": "content", "pagesRead": 6 }]
    }
  ],
  "limit": 25,
  "offset": 25,
  "total": 40,
  "hasMore": false
}
```

`outcome` is `content-read`, `toc-only` or `no-read`. The errors are the same as for the report.

## Start a research session

`POST https://heytrove.ai/api/v1/access/session`

Opens a research session. Send the returned id in the `X-CK-Session` header on later reads so they are recorded under it.

**Parameters**

| Name | In | Type | Required | Constraints | Meaning |
| --- | --- | --- | --- | --- | --- |
| `intent` | body | string | no | up to 500 characters | One line about the topic. Keep out anything personal or secret. |

**Request**

```bash
curl https://heytrove.ai/api/v1/access/session \
  -H "Authorization: Bearer trove_your_key" \
  -H "Content-Type: application/json" \
  -d '{"intent":"retry strategy for flaky jobs"}'
```

**Response**

Status 201.

```json
{ "sessionId": "cmsess1", "createdAt": "2026-10-01T08:00:00.000Z" }
```

A later read then carries the id.

```bash
curl -X POST https://heytrove.ai/api/v1/items/batch \
  -H "Authorization: Bearer trove_your_key" \
  -H "X-CK-Session: cmsess1" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"id":"cmabc123","pages":"10-12"}]}'
```

**Errors**

| Status | Message | Code | Fix |
| --- | --- | --- | --- |
| 400 | `intent must be 500 characters or less` | none | Shorten it. |
| 429 | `Too many active sessions. Complete or wait for existing sessions to expire.` | none | Complete an open session. |
| 429 | `Session creation rate limit exceeded. Try again later.` | none | Wait. |

## Complete a research session

`POST https://heytrove.ai/api/v1/access/session/complete`

Closes a session. Calling it again for a closed session returns the same answer.

**Parameters**

| Name | In | Type | Required | Constraints | Meaning |
| --- | --- | --- | --- | --- | --- |
| `sessionId` | body | string | yes | a session you own | Session to close. |

**Request**

```bash
curl https://heytrove.ai/api/v1/access/session/complete \
  -H "Authorization: Bearer trove_your_key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"cmsess1"}'
```

**Response**

```json
{ "sessionId": "cmsess1", "status": "completed" }
```

**Errors**

| Status | Message | Code | Fix |
| --- | --- | --- | --- |
| 400 | `sessionId is required` | none | Send `sessionId`. |
| 404 | `Session not found` | none | Check the id. |