Skip to main content

​
ReportsClient

The main client class for interacting with the Nebuly reports API.

​
Constructor

​
publicKey
string
required
Your Nebuly public API key. Must not be a secret key (starting with sk-).
​
retries
number
default:"0"
Number of retry attempts for failed requests.
​
retryDelay
number
default:"1000"
Delay in milliseconds between retry attempts.
​
baseUrl
string
default:"https://backend.nebuly.com/api/external"
Base URL for the Nebuly API.
​
suppressKeyError
boolean
default:"false"
Whether to suppress errors when a secret key is used instead of a public key.
​
supperssKeyErrorLog
boolean
default:"false"
Whether to suppress console error logs when a secret key is used.

​
Methods

​
listReports()

Retrieves a list of all available reports.
​
reports
Report[]
Array of report objects containing basic report information.

​
getReport(params)

Retrieves detailed data for a specific report.
​
reportId
string
required
The unique identifier of the report to retrieve.
​
timeRange
TimeRange
Optional time range filter for the report data.
​
tags
Record<string, string | string[]>
Optional tags to filter the report data. Values can be strings or arrays of strings.
​
reportData
ReportData
The report data containing charts and metadata.

​
Types

​
Report

​
id
string
Unique identifier for the report.
​
name
string
Display name of the report.
​
description
string
Description of the report.

​
ReportData

​
id
string
Unique identifier for the report.
​
name
string
Display name of the report.
​
charts
ChartData[]
Array of chart data objects within the report.

​
ChartData

​
id
string
Unique identifier for the chart (prefixed with “chart-”).
​
name
string
Display name of the chart.
​
type
string
Type of the chart.
​
variables
string[]
Array of variable names used in the chart.
​
visualizationType
string
Type of visualization for the chart.
​
displayType
string
Display type for the chart.
​
breakdown
string
Breakdown dimension for the chart data.
​
timeRange
TimeRange
Time range for the chart data.
​
granularity
string
Time granularity for the chart data.
​
xLabelValues
string[]
Array of x-axis label values.
​
data
DatasetDatapoint[]
Array of data points for the chart.

​
TimeRange

​
kind
TimeRangeKind
The type of time range (e.g., “custom”, “today”, “7_days”, etc.).
​
start
string
Start date/time for the range (ISO format).
​
end
string
End date/time for the range (ISO format).

​
TimeRangeKind

Available time range kinds:
  • "custom" - Custom date range
  • "date_to_now" - From a specific date to now
  • "today" - Today only
  • "yesterday" - Yesterday only
  • "7_days" - Last 7 days
  • "30_days" - Last 30 days
  • "this_month" - Current month
  • "this_quarter" - Current quarter
  • "this_year" - Current year
  • "last_month" - Previous month
  • "last_quarter" - Previous quarter
  • "3_months" - Last 3 months
  • "6_months" - Last 6 months
  • "12_months" - Last 12 months
  • "3_months_full" - Last 3 full months
  • "6_months_full" - Last 6 full months
  • "12_months_full" - Last 12 full months
  • "q1" - Q1
  • "q2" - Q2
  • "q3" - Q3
  • "q4" - Q4
  • "ytd" - Year to date

​
DatasetDatapoint

​
label
string
Label for the data point.
​
data
Array<{x: number, y: number, user?: string}>
Array of coordinate data points with optional user information.

​
Error Handling

The client throws InvalidUrlError when an invalid base URL is provided during initialization.

​
Example Usage

import NebulyReports from '@nebuly-ai/reports';

const client = new NebulyReports.Client({
  publicKey: 'your-public-key-here',
  retries: 3,
  retryDelay: 1000
});

// List all reports
const reports = await client.listReports();

// Get specific report data
const reportData = await client.getReport({
  reportId: 'report-123',
  timeRange: {
    kind: '7_days',
    start: '2024-01-01T00:00:00Z',
    end: '2024-01-08T00:00:00Z'
  },
  tags: {
    environment: 'production',
    team: ['frontend', 'backend']
  }
});
⌘I