limitry.client.Usage

class limitry.client.Usage[source]

Bases: object

Operations for usage.

__init__(client)[source]

Initialize Usage operations.

Parameters:

client (Client) – The Limitry client instance

Return type:

None

Methods

__init__(client)

Initialize Usage operations.

get_breakdown(group_by, start_date, end_date)

Get usage breakdown.

get_summary(start_date, end_date[, ...])

Get usage summary.

get_timeseries(interval, start_date, end_date)

Get usage timeseries.
__init__(client)[source]

Initialize Usage operations.

Parameters:

client (Client) – The Limitry client instance

Return type:

None

async get_summary(start_date, end_date, customer_id=None, event_type=None, model=None)[source]

Get usage summary.

Retrieve aggregated usage metrics for the project.

Returns totals for events, tokens, and costs within the specified date range. You can filter by customer, event type, or model to get specific subsets of data.

Metrics Included: - Total events count - Total tokens (input + output) - Total input tokens - Total output tokens - Total cost in cents.

Parameters:

  • customer_id (Optional[str]) – Filter usage by customer ID

  • event_type (Optional[str]) – Filter usage by event type (e.g., “model_call”, “embedding”)

  • model (Optional[str]) – Filter usage by model name (e.g., “gpt-4”, “claude-3”)

  • start_date (str) – Start of the date range (ISO 8601 format) (ISO 8601 format, e.g., “2024-01-01T00:00:00Z”)

  • end_date (str) – End of the date range (ISO 8601 format) (ISO 8601 format, e.g., “2024-01-01T00:00:00Z”)

Returns:

Usage summary

Return type:

UsageSummary

Example:

result = await client.usage.get_summary(
    start_date="2024-01-01T00:00:00Z",
    end_date="2024-01-01T00:00:00Z"
)
print(result)
Raises:
Parameters:

  • start_date (str)

  • end_date (str)

  • customer_id (str | None)

  • event_type (str | None)

  • model (str | None)

Return type:

UsageSummary

async get_breakdown(group_by, start_date, end_date, customer_id=None, event_type=None, model=None)[source]

Get usage breakdown.

Retrieve usage metrics grouped by a specific dimension.

This endpoint provides detailed breakdowns of usage data, allowing you to see how usage is distributed across different dimensions like models, customers, event types, or providers.

Use Cases: - See which models consume the most tokens - Identify top customers by usage - Compare usage across different event types - Analyze provider-specific consumption.

Parameters:

  • group_by (str) – Dimension to group usage by (one of: “model”, “customer_id”, “event_type”, “provider”)

  • customer_id (Optional[str]) – Filter usage by customer ID before grouping

  • event_type (Optional[str]) – Filter usage by event type before grouping

  • model (Optional[str]) – Filter usage by model name before grouping

  • start_date (str) – Start of the date range (ISO 8601 format) (ISO 8601 format, e.g., “2024-01-01T00:00:00Z”)

  • end_date (str) – End of the date range (ISO 8601 format) (ISO 8601 format, e.g., “2024-01-01T00:00:00Z”)

Returns:

Usage breakdown

Return type:

UsageBreakdownResponse

Example:

result = await client.usage.get_breakdown(
    group_by="example",
    start_date="2024-01-01T00:00:00Z",
    end_date="2024-01-01T00:00:00Z"
)
print(result)
Raises:
Parameters:

  • group_by (str)

  • start_date (str)

  • end_date (str)

  • customer_id (str | None)

  • event_type (str | None)

  • model (str | None)

Return type:

UsageBreakdownResponse

async get_timeseries(interval, start_date, end_date, customer_id=None, event_type=None, model=None)[source]

Get usage timeseries.

Retrieve usage metrics bucketed by time interval.

Returns time-series data showing how usage changes over time. Useful for creating charts, identifying trends, and monitoring usage patterns.

Intervals: - hour: Bucket data by hour - day: Bucket data by day - week: Bucket data by week

Each data point includes the timestamp and all usage metrics for that time period.

Parameters:

  • interval (str) – Time interval for bucketing data (one of: “hour”, “day”, “week”)

  • customer_id (Optional[str]) – Filter usage by customer ID

  • event_type (Optional[str]) – Filter usage by event type

  • model (Optional[str]) – Filter usage by model name

  • start_date (str) – Start of the date range (ISO 8601 format) (ISO 8601 format, e.g., “2024-01-01T00:00:00Z”)

  • end_date (str) – End of the date range (ISO 8601 format) (ISO 8601 format, e.g., “2024-01-01T00:00:00Z”)

Returns:

Usage timeseries

Return type:

UsageTimeseriesResponse

Example:

result = await client.usage.get_timeseries(
    interval="example",
    start_date="2024-01-01T00:00:00Z",
    end_date="2024-01-01T00:00:00Z"
)
print(result)
Raises:
Parameters:

  • interval (str)

  • start_date (str)

  • end_date (str)

  • customer_id (str | None)

  • event_type (str | None)

  • model (str | None)

Return type:

UsageTimeseriesResponse