alephantai-analytics-api 0.1.0

Python client for Alephant Analytics API

Alephant Analytics API Python Client

Official Python client for the Alephant Analytics API.

Installation

pip install alephantai-analytics-api

Package Import

After installation, import the client using the Python package name:

# PyPI package name: alephantai-analytics-api  
# Python import name: alephant_logs_collector
from alephant_logs_collector import LogsCollectorAnalyticsClient

Note: The PyPI package name (alephantai-analytics-api) differs from the Python import name (alephant_logs_collector) due to Fern generator naming conventions.

Quick Start

import os

from alephant_logs_collector import LogsCollectorAnalyticsClient
from alephant_logs_collector.environment import LogsCollectorAnalyticsClientEnvironment

# Manually read environment variables and configure client
api_key = os.environ.get("ALEPHANT_API_KEY")
client = LogsCollectorAnalyticsClient(
    environment=LogsCollectorAnalyticsClientEnvironment.PRODUCTION,
    headers={"Authorization": f"Bearer {api_key}"} if api_key else None,
)

# Public health probe (auth optional)
health = client.analytics_atomic.get_health()
print(f"Service status: {health.data.status}")

Configuration

Environment Variables

The SDK does not automatically read environment variables. You must manually read them in your code and pass them to the client constructor.

Recommended environment variables:

Variable	Description
ALEPHANT_API_KEY	Your API key, virtual key, or PAT — passed as Bearer token via headers parameter
ALEPHANT_BASE_URL	Base URL for the API (e.g. https://analytics.alephant.io) — passed via base_url parameter

Example with manual environment variable reading:

import os

from alephant_logs_collector import LogsCollectorAnalyticsClient

# Manually read environment variables
base_url = os.environ.get("ALEPHANT_BASE_URL")
api_key = os.environ.get("ALEPHANT_API_KEY")

client = LogsCollectorAnalyticsClient(
    base_url=base_url,
    headers={"Authorization": f"Bearer {api_key}"} if api_key else None,
)

Client Options

from alephant_logs_collector import LogsCollectorAnalyticsClient
from alephant_logs_collector.environment import LogsCollectorAnalyticsClientEnvironment

client = LogsCollectorAnalyticsClient(
    environment=LogsCollectorAnalyticsClientEnvironment.PRODUCTION,
    base_url="https://analytics.alephant.io",  # optional; overrides environment URL when set
    timeout=30.0,  # seconds; default 60 when using the default httpx client
    follow_redirects=True,
    headers=None,  # default headers for every request (e.g. Authorization, Cookie)
)

Authentication

The API accepts Bearer JWT, virtual key, or PAT on the Authorization header. The Python client does not expose a dedicated api_key constructor argument; wire credentials using one of the patterns below.

API Key (Bearer token)

Pass the token on each call, or set default headers on the client.

import os

from alephant_logs_collector import LogsCollectorAnalyticsClient
from alephant_logs_collector.environment import LogsCollectorAnalyticsClientEnvironment

token = os.environ["ALEPHANT_API_KEY"]

client = LogsCollectorAnalyticsClient(
    environment=LogsCollectorAnalyticsClientEnvironment.PRODUCTION,
    headers={"Authorization": f"Bearer {token}"},
)

# Or per-request (overrides / supplements per method signature)
client.analytics_atomic.get_live24h_summary(
    authorization=f"Bearer {token}",
    x_workspace_id="00000000-0000-0000-0000-000000000000",
)

JWT Token

Use the same Authorization: Bearer <jwt> form — either via headers= on the client or the authorization= parameter on endpoints.

client = LogsCollectorAnalyticsClient(
    base_url="https://analytics.alephant.io",
    headers={"Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."},
)

Cookie Auth

The server also accepts the alephant_token cookie. Model it with default headers (or a custom httpx client):

import httpx
from alephant_logs_collector import LogsCollectorAnalyticsClient

cookie_client = httpx.Client(timeout=30.0)
client = LogsCollectorAnalyticsClient(
    base_url="https://analytics.alephant.io",
    httpx_client=cookie_client,
    headers={"Cookie": "alephant_token=YOUR_SESSION_TOKEN"},
)

Authenticated routes typically require x_workspace_id (X-Workspace-Id) as well — pass x_workspace_id="..." on each method that supports it.

API Reference

For full request/response shapes, see reference.md in this package.

Analytics Atomic

Method	Description
client.analytics_atomic.get_health()	Public health probe (GET health).
client.analytics_atomic.post_aggregate_ping()	Connectivity check against aggregate tables.
client.analytics_atomic.post_detail_ping()	Connectivity check against detail/RMT paths.
client.analytics_atomic.get_live24h_summary()	Rolling ~24h workspace totals.
client.analytics_atomic.get_usage_summary()	Daily KPIs for a window vs previous period.
client.analytics_atomic.get_usage_timeseries()	Time series for cost/requests/tokens/etc.
client.analytics_atomic.get_request_logs(start=..., end=...)	Request log list for a time window.
client.analytics_atomic.get_request_log_by_id(request_id=...)	Single request log by ID.
client.analytics_atomic.get_by_department() / get_by_agent() / get_by_member()	Cost/usage breakdown helpers.
client.analytics_atomic.get_master_keys_*()	Master key vault, spend, and breakdown endpoints.

Analytics SaaS

Method	Description
client.analytics_saas.get_saas_overview()	SaaS dashboard overview.
client.analytics_saas.get_saas_live24h()	Live-24h style panel (top models/keys, etc.).
client.analytics_saas.get_saas_usage(date_from=..., date_to=...)	Daily usage series for the workspace.
client.analytics_saas.get_saas_logs(...)	SaaS request logs listing (filters per API).
client.analytics_saas.get_saas_logs_stats()	Log statistics for the SaaS UI.
client.analytics_saas.get_saas_costs() / get_saas_models() / get_saas_sparklines()	Costs, models, sparklines.
client.analytics_saas.get_saas_agent_analytics() / get_saas_member_analytics()	Agent/member analytics.

Error Handling

Non-2xx responses and some parse failures raise ApiError from alephant_logs_collector.core.

from alephant_logs_collector import LogsCollectorAnalyticsClient
from alephant_logs_collector.core import ApiError
from alephant_logs_collector.environment import LogsCollectorAnalyticsClientEnvironment

client = LogsCollectorAnalyticsClient(
    environment=LogsCollectorAnalyticsClientEnvironment.PRODUCTION,
    headers={"Authorization": "Bearer your-token"},
)

try:
    data = client.analytics_atomic.get_request_logs(
        start="2025-01-01T00:00:00Z",
        end="2025-01-02T00:00:00Z",
        x_workspace_id="your-workspace-uuid",
    )
    print(data)
except ApiError as e:
    # e.status_code: HTTP status; e.body: parsed JSON or raw text; e.headers: response headers
    print(f"API error: status={e.status_code}, body={e.body}")

Async Support

Use AsyncLogsCollectorAnalyticsClient with async/await. Method names mirror the sync client.

import asyncio
import os

from alephant_logs_collector import AsyncLogsCollectorAnalyticsClient
from alephant_logs_collector.environment import LogsCollectorAnalyticsClientEnvironment


async def main() -> None:
    # Manually read environment variables
    api_key = os.environ.get("ALEPHANT_API_KEY")
    client = AsyncLogsCollectorAnalyticsClient(
        environment=LogsCollectorAnalyticsClientEnvironment.PRODUCTION,
        headers={"Authorization": f"Bearer {api_key}"} if api_key else None,
    )
    health = await client.analytics_atomic.get_health()
    print(health.data.status)


asyncio.run(main())

Development

From the directory that contains pyproject.toml (this SDK root):

Installing Dev Dependencies

pip install -e ".[dev]"

Running Tests

pytest

Code Formatting

black .
isort .

Type Checking

mypy .

License

This project is licensed under the MIT License — see the LICENSE file for details.

Support

For support, contact [e-mail] or open an issue on GitHub.

Documentation

See Alephant Analytics API documentation and the generated reference.md in this repository for endpoint-level detail.