Python SDK | Alephant Documentation

The official Alephant Analytics Python SDK provides access to the Alephant Analytics API from Python scripts or data science notebooks. It supports both synchronous and asynchronous execution.

Installation

Install the SDK via pip:

$ pip install alephantai-analytics-api

Initialization

You can initialize either a synchronous or asynchronous client depending on your architecture.

Synchronous Client

1 import os
2 from alephant_logs_collector import (
3     LogsCollectorAnalyticsClient,
4     LogsCollectorAnalyticsClientEnvironment,
5 )
6 
7 client = LogsCollectorAnalyticsClient(
8     environment=LogsCollectorAnalyticsClientEnvironment.DEVELOPMENT,
9 )

Asynchronous Client

Ideal for FastAPI, async web frameworks, or highly concurrent applications:

1 import os
2 from alephant_logs_collector import (
3     AsyncLogsCollectorAnalyticsClient,
4     LogsCollectorAnalyticsClientEnvironment,
5 )
6 
7 async_client = AsyncLogsCollectorAnalyticsClient(
8     environment=LogsCollectorAnalyticsClientEnvironment.DEVELOPMENT,
9 )

Example Usage

Smoke test

Use the public health endpoint to verify that the SDK can reach the Analytics dev service.

1 response = client.analytics_atomic.get_health()
2 print(response.data.status)

Live 24-Hour Panel Overview

Retrieve a rolling live-24h dashboard style panel of top models and keys.

1 def fetch_live_summary():
2     try:
3         response = client.analytics_saas.get_saas_live24h(
4             limit=5,
5             authorization=f"Bearer {os.environ['ALEPHANT_API_TOKEN']}",
6             x_workspace_id=os.environ["ALEPHANT_WORKSPACE_ID"],
7         )
8         print(response.data)
9     except Exception as e:
10         print(f"Failed to fetch live summary: {e}")

Retrieving usage series

Fetch daily usage metrics over a specified date range.

1 async def get_usage_series():
2     response = await async_client.analytics_saas.get_saas_usage(
3         date_from="2026-03-01",
4         date_to="2026-03-31",
5         authorization=f"Bearer {os.environ['ALEPHANT_API_TOKEN']}",
6         x_workspace_id=os.environ["ALEPHANT_WORKSPACE_ID"],
7     )
8 
9     print(response.data)

Error Handling

Any request that results in a 4xx or 5xx status code will raise an exception corresponding to the type of error (ApiError, RateLimitError, etc.). Catch these natively in Python to perform fallback logic or exponential backoffs.