Reference
Reports API
Updated 1 Oct 2026
On this page
For agents
Load this page when: you need the value report, or you need to record reads under a research session over HTTP
- 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.
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
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.
{
"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.
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
curl "https://heytrove.ai/api/v1/reports/value/sessions?since=30d&sessionsLimit=25&sessionsOffset=25" \
-H "Authorization: Bearer trove_your_key"Response
{
"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
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.
{ "sessionId": "cmsess1", "createdAt": "2026-10-01T08:00:00.000Z" }A later read then carries the id.
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
curl https://heytrove.ai/api/v1/access/session/complete \
-H "Authorization: Bearer trove_your_key" \
-H "Content-Type: application/json" \
-d '{"sessionId":"cmsess1"}'Response
{ "sessionId": "cmsess1", "status": "completed" }Errors
| Status | Message | Code | Fix |
|---|---|---|---|
| 400 | sessionId is required | none | Send sessionId. |
| 404 | Session not found | none | Check the id. |