***

title: Python SDK
subtitle: Integrate Alephant Analytics into your Python applications
description: 'Installation, configuration, and usage of the Alephant Analytics Python SDK'
------------------------------------------------------------------------------------------

The official Alephant Analytics Python SDK provides convenient access to the Alephant Analytics API from Python scripts or data science notebooks. It supports both synchronous and asynchronous execution, enabling high-performance queries for dashboards, AI cost optimization, and alerting engines.

## 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 alephantai_analytics import AlephantAnalytics, AlephantAnalyticsEnvironment

client = AlephantAnalytics(
    # Set the target environment
    environment=AlephantAnalyticsEnvironment.DEFAULT,
    # Pass your API token
    token=f"Bearer {os.getenv('ALEPHANT_API_TOKEN')}",
    # Pass the Workspace ID mapping
    workspace_id=os.getenv('ALEPHANT_WORKSPACE_ID')
)
```

### Asynchronous Client

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

```python
import os
from alephantai_analytics import AsyncAlephantAnalytics, AlephantAnalyticsEnvironment

async_client = AsyncAlephantAnalytics(
    environment=AlephantAnalyticsEnvironment.DEFAULT,
    token=f"Bearer {os.getenv('ALEPHANT_API_TOKEN')}",
    workspace_id=os.getenv('ALEPHANT_WORKSPACE_ID')
)
```

## Example Usage

### 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.saas.get_saas_live_24h(limit=5)
        print(f"Top Model: {response.data.top_model}")
        print(f"Total Requests: {response.data.total_requests}")
    except Exception as e:
        print(f"Failed to fetch live summary: {e}")
```

### Retrieving Department Overrides and Analytics

Fetch cost breakdowns for a specific department.

```python
async def get_department_cost_breakdown(department_id: str):
    response = await async_client.departments.cost_breakdown(
        department_id=department_id,
        preset="30d", # Compare last 30 days
        limit=50
    )
    
    print(f"Current Period Cost: {response.data.summary.cost_sum}")
    for row in response.data.rows:
        print(f"Agent: {row.agent_name} | Spend: ${row.spend}")
```

## 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.