> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/sdk-reference/analytics-sdk/python-sdk/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Python SDK

> Installation, configuration, and usage of the Alephant Analytics Python SDK

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:

```bash
pip install alephantai-analytics-api
```

## Initialization

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

### Synchronous Client

```python
import os
from alephant_logs_collector import (
    LogsCollectorAnalyticsClient,
    LogsCollectorAnalyticsClientEnvironment,
)

client = LogsCollectorAnalyticsClient(
    environment=LogsCollectorAnalyticsClientEnvironment.DEVELOPMENT,
)
```

### Asynchronous Client

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

```python
import os
from alephant_logs_collector import (
    AsyncLogsCollectorAnalyticsClient,
    LogsCollectorAnalyticsClientEnvironment,
)

async_client = AsyncLogsCollectorAnalyticsClient(
    environment=LogsCollectorAnalyticsClientEnvironment.DEVELOPMENT,
)
```

## Example Usage

### Smoke test

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

```python
response = client.analytics_atomic.get_health()
print(response.data.status)
```

### Live 24-Hour Panel Overview

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

```python
def fetch_live_summary():
    try:
        response = client.analytics_saas.get_saas_live24h(
            limit=5,
            authorization=f"Bearer {os.environ['ALEPHANT_API_TOKEN']}",
            x_workspace_id=os.environ["ALEPHANT_WORKSPACE_ID"],
        )
        print(response.data)
    except Exception as e:
        print(f"Failed to fetch live summary: {e}")
```

### Retrieving usage series

Fetch daily usage metrics over a specified date range.

```python
async def get_usage_series():
    response = await async_client.analytics_saas.get_saas_usage(
        date_from="2026-03-01",
        date_to="2026-03-31",
        authorization=f"Bearer {os.environ['ALEPHANT_API_TOKEN']}",
        x_workspace_id=os.environ["ALEPHANT_WORKSPACE_ID"],
    )

    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.

> Integrate Alephant Analytics into your Python applications