Browsing Reports
This page covers the three read-only methods for exploring discovery reports: listing reports with pagination and tag filtering, getting curated query suggestions, and fetching the full content of a single report.
Listing Reports
list(params?) returns a paginated collection of published discovery reports. All parameters are optional — calling list() with no arguments returns the first page with the default page size.
Parameters (DiscoveryListParams):
| Param | Type | Description |
|---|---|---|
page | number | Page number (1-indexed) |
limit | number | Results per page |
tag | string | Filter reports by tag |
Returns: DiscoveryListResponse — an object with total (the full count of matching reports) and data (an array of DiscoveryReport objects for the current page).
import { Chaos } from '@chaoslabs/ai-sdk';
const chaos = new Chaos({ apiKey: process.env.CHAOS_API_KEY! });
// Fetch the first page of reports
const { data: reports, total } = await chaos.discovery.list({
page: 1,
limit: 10,
});
console.log(`Page 1 of ${Math.ceil(total / 10)} (${total} reports total)\n`);
for (const report of reports) {
console.log(`${report.title}`);
console.log(` Tags: ${report.tags.join(', ')}`);
console.log(` Updated: ${report.updated_at}`);
console.log(` Author: ${report.updated_by.name}\n`);
}// Filter reports by tag
const defiReports = await chaos.discovery.list({
tag: 'defi',
page: 1,
limit: 5,
});
console.log(`${defiReports.total} reports tagged "defi"`);
for (const report of defiReports.data) {
console.log(` ${report.title}`);
}Suggested Queries
suggestedQueries(limit?) returns curated report summaries with recommended queries that users can ask. This is useful for building exploration UIs or onboarding flows.
Parameters:
| Param | Type | Description |
|---|---|---|
limit | number | Maximum number of report summaries to return |
Returns: LatestDiscoveryResponse — an object with a reports array of DiscoveryReportSummary objects. Each summary includes a suggested_user_queries array.
The summary object is lighter than a full DiscoveryReport — it omits description, updated_by, and sources.
import { Chaos } from '@chaoslabs/ai-sdk';
const chaos = new Chaos({ apiKey: process.env.CHAOS_API_KEY! });
const { reports } = await chaos.discovery.suggestedQueries(5);
for (const report of reports) {
console.log(`\n${report.title} [${report.tags.join(', ')}]`);
for (const q of report.suggested_user_queries) {
console.log(` ${q.query} (${q.query_type})`);
}
}Fetching Report Details
get(sessionId) returns the full content of a single discovery report, including rendered content blocks, source references, and suggested follow-up questions.
Parameters:
| Param | Type | Description |
|---|---|---|
sessionId | string | The report's id from a list or summary response |
Returns: DiscoveryReportDetails — extends DiscoveryReport with two additional fields: content (an array of rendered content blocks) and followup_questions (an array of suggested follow-up strings).
A typical workflow is to list reports with list(), then call get() with a selected report's id to load its full content.
import { Chaos } from '@chaoslabs/ai-sdk';
const chaos = new Chaos({ apiKey: process.env.CHAOS_API_KEY! });
// Step 1: Get a report ID from the list
const { data: reports } = await chaos.discovery.list({ limit: 1 });
const reportId = reports[0].id;
// Step 2: Fetch full details
const detail = await chaos.discovery.get(reportId);
console.log(`Title: ${detail.title}`);
console.log(`Description: ${detail.description}`);
console.log(`Content blocks: ${detail.content.length}`);
console.log('\nSources:');
for (const src of detail.sources) {
console.log(` ${src.title ?? src.url}`);
}
console.log('\nSuggested follow-ups:');
for (const q of detail.followup_questions) {
console.log(` ${q}`);
}