***

title: Typescript SDK
subtitle: Integrate Alephant Analytics into your TypeScript & Node.js applications
description: >-
Installation, configuration, and usage of the Alephant Analytics TypeScript
SDK
---

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:

```bash
npm install @alephantai/analytics-api
```

## Initialization

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

```typescript
import { AlephantAnalytics } from '@alephantai/analytics-api';

const client = new AlephantAnalytics({
  // Your API Token
  token: process.env.ALEPHANT_API_TOKEN,
  // Pass the Workspace ID for authorized context
  workspaceId: process.env.ALEPHANT_WORKSPACE_ID,
});
```

## Example Usage

### Fetching Usage Summaries

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

```typescript
async function fetchUsageSummary() {
  try {
    const response = await client.usage.getUsageSummary({
      preset: "30d", // Retrieve last 30 days
    });
    
    console.log("Current Period Cost:", response.data.current.cost_sum);
    console.log("Previous Period Cost:", response.data.previous.cost_sum);
  } catch (error) {
    console.error("Failed to fetch usage summary:", error);
  }
}
```

### Retrieving Time-Series Data

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

```typescript
async function fetchCostTimeseries() {
  const response = await client.usage.getUsageTimeseries({
    metric: "cost",
    granularity: "day",
    start: "2026-03-01",
    end: "2026-03-31",
  });
  
  response.data.points.forEach(point => {
    console.log(`Date: ${point.bucket} | Cost: $${point.value}`);
  });
}
```

## Error Handling

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