Typescript SDK | Alephant API Documentation

The official Alephant Analytics TypeScript SDK provides convenient access to the Alephant Analytics API from TypeScript and Node.js applications. It allows you to query telemetry, fetch daily usage series, and retrieve real-time summary statistics for FinOps dashboards.

Installation

Install the SDK via npm, yarn, or pnpm:

$ npm install @alephantai/analytics-api

Initialization

Import and initialize the client with your Personal Access Token (ALEPHANT_PAT) or a Virtual Key.

1 import { AlephantAnalytics } from '@alephantai/analytics-api';
2 
3 const client = new AlephantAnalytics({
4   // Your API Token
5   token: process.env.ALEPHANT_API_TOKEN,
6   // Pass the Workspace ID for authorized context
7   workspaceId: process.env.ALEPHANT_WORKSPACE_ID,
8 });

Example Usage

Fetching Usage Summaries

Retrieve high-level, daily-aggregate KPIs for a specific window, including comparisons to the previous period.

1 async function fetchUsageSummary() {
2   try {
3     const response = await client.usage.getUsageSummary({
4       preset: "30d", // Retrieve last 30 days
5     });
6     
7     console.log("Current Period Cost:", response.data.current.cost_sum);
8     console.log("Previous Period Cost:", response.data.previous.cost_sum);
9   } catch (error) {
10     console.error("Failed to fetch usage summary:", error);
11   }
12 }

Retrieving Time-Series Data

Fetch fine-grained time-series metrics over a specified date range.

1 async function fetchCostTimeseries() {
2   const response = await client.usage.getUsageTimeseries({
3     metric: "cost",
4     granularity: "day",
5     start: "2026-03-01",
6     end: "2026-03-31",
7   });
8   
9   response.data.points.forEach(point => {
10     console.log(`Date: ${point.bucket} | Cost: $${point.value}`);
11   });
12 }

Error Handling

The SDK throws structured errors for non-2xx API responses, allowing you to gracefully handle authentication, rate limits, or validation errors programmatically.