# OpenMeter Python SDK [On PyPI](https://pypi.org/project/openmeter) This package is generated by `@typespec/http-client-python` with Typespec. ## Prerequisites - Python 3.9 or later is required to use this package. ## Install > The Python SDK is in preview mode. ```sh pip install --pre openmeter # or using an exact version pip install openmeter==1.0.0bXXX ``` ## Examples ### Setup #### Synchronous Client ```python from openmeter import Client client = Client( endpoint="https://openmeter.cloud", token="your-api-token", ) ``` #### Async Client ```python from openmeter.aio import Client client = Client( endpoint="https://openmeter.cloud", token="your-api-token", ) ``` ### Ingest an Event #### Synchronous ```python import datetime import uuid from openmeter.models import Event # Create an Event instance (following CloudEvents specification) event = Event( id=str(uuid.uuid4()), source="my-app", specversion="1.0", type="prompt", subject="customer-1", time=datetime.datetime.now(datetime.timezone.utc), data={ "tokens": 100, "model": "gpt-4o", "type": "input", }, ) # Ingest the event client.events.ingest_event(event) ``` #### Async ```python import datetime import uuid import asyncio from openmeter.aio import Client from openmeter.models import Event async def main(): async with Client( endpoint="https://openmeter.cloud", token="your-api-token", ) as client: # Create an Event instance (following CloudEvents specification) event = Event( id=str(uuid.uuid4()), source="my-app", specversion="1.0", type="prompt", subject="customer-1", time=datetime.datetime.now(datetime.timezone.utc), data={ "tokens": 100, "model": "gpt-4o", "type": "input", }, ) # Ingest the event await client.events.ingest_event(event) asyncio.run(main()) ``` ### Query Meter #### Synchronous ```python from openmeter.models import MeterQueryResult # Query total values r: MeterQueryResult = client.meters.query_json(meter_id_or_slug="tokens_total") print("Query total values:", r.data[0].value) ``` #### Async ```python import asyncio from openmeter.aio import Client from openmeter.models import MeterQueryResult async def main(): async with Client( endpoint="https://openmeter.cloud", token="your-api-token", ) as client: # Query total values r: MeterQueryResult = await client.meters.query_json( meter_id_or_slug="tokens_total" ) print("Query total values:", r.data[0].value) asyncio.run(main()) ``` ## Client API Reference The OpenMeter Python SDK provides a comprehensive client interface organized into logical operation groups. Below is a complete reference of all available methods. ### Overview | Namespace | Operation | Method | Description | | ---------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | | **Events** | | | Track usage by ingesting events | | | Create | `client.events.ingest_event(event)` | Ingest a single event | | | Create | `client.events.ingest_events(events)` | Ingest batch of events | | | Create | `client.events.ingest_events_json(events_json)` | Ingest events from JSON | | | Read | `client.events.list(**kwargs)` | List ingested events with filtering | | | Read | `client.events_v2.list(**kwargs)` | List ingested events with advanced filtering (V2) | | **Meters** | | | Track and aggregate usage data from events | | | Create | `client.meters.create(meter)` | Create a new meter | | | Read | `client.meters.get(meter_id_or_slug)` | Get a meter by ID or slug | | | Read | `client.meters.list(**kwargs)` | List all meters | | | Read | `client.meters.query_json(meter_id_or_slug, **kwargs)` | Query usage data in JSON format | | | Read | `client.meters.query_csv(meter_id_or_slug, **kwargs)` | Query usage data in CSV format | | | Read | `client.meters.query(meter_id_or_slug, **kwargs)` | Query usage data | | | Read | `client.meters.list_subjects(meter_id_or_slug, **kwargs)` | List subjects for a meter | | | Read | `client.meters.list_group_by_values(meter_id_or_slug, **kwargs)` | List group-by values for a meter | | | Update | `client.meters.update(meter_id_or_slug, meter)` | Update a meter by ID or slug | | | Delete | `client.meters.delete(meter_id_or_slug)` | Delete a meter by ID or slug | | **Subjects** | | | Manage entities that consume resources | | | Create | `client.subjects.upsert(subjects)` | Create or update one or multiple subjects | | | Read | `client.subjects.get(subject_id_or_key)` | Get a subject by ID or key | | | Read | `client.subjects.list()` | List all subjects | | | Delete | `client.subjects.delete(subject_id_or_key)` | Delete a subject by ID or key | | **Customers** | | | Manage customer information and lifecycles | | | Create | `client.customers.create(customer)` | Create a new customer | | | Read | `client.customers.get(customer_id_or_key, **kwargs)` | Get a customer by ID or key | | | Read | `client.customers.list(**kwargs)` | List all customers | | | Read | `client.customers.list_customer_subscriptions(customer_id_or_key, **kwargs)` | List customer subscriptions | | | Update | `client.customers.update(customer_id_or_key, customer)` | Update a customer | | | Delete | `client.customers.delete(customer_id_or_key)` | Delete a customer | | **Customer (Single)** | | | Customer-specific operations | | | Read | `client.customer.get_customer_access(customer_id_or_key)` | Get customer access information | | **Customer Apps** | | | Manage customer app integrations | | | Read | `client.customer_apps.list_app_data(customer_id_or_key, **kwargs)` | List app data for a customer | | | Update | `client.customer_apps.upsert_app_data(customer_id_or_key, app_data)` | Upsert app data for a customer | | | Delete | `client.customer_apps.delete_app_data(customer_id_or_key, app_id)` | Delete app data for a customer | | **Customer Stripe** | | | Manage Stripe integration for customers | | | Read | `client.customer_stripe.get(customer_id_or_key)` | Get Stripe customer data | | | Update | `client.customer_stripe.upsert(customer_id_or_key, data)` | Upsert Stripe customer data | | | Create | `client.customer_stripe.create_portal_session(customer_id_or_key, **kwargs)` | Create a Stripe customer portal session | | **Customer Entitlement** | | | Single customer entitlement operations | | | Read | `client.customer_entitlement.get_customer_entitlement_value(customer_id_or_key, **kwargs)` | Get customer entitlement value | | **Customer Overrides** | | | Manage customer-specific pricing overrides | | | Read | `client.customer_overrides.list(customer_id_or_key)` | List customer overrides | | | Read | `client.customer_overrides.get(customer_id_or_key, override_id)` | Get a customer override | | | Update | `client.customer_overrides.upsert(customer_id_or_key, override)` | Upsert a customer override | | | Delete | `client.customer_overrides.delete(customer_id_or_key, override_id)` | Delete a customer override | | **Features** | | | Define application capabilities and services | | | Create | `client.features.create(feature)` | Create a new feature | | | Read | `client.features.get(feature_id)` | Get a feature by ID | | | Read | `client.features.list(**kwargs)` | List all features | | | Delete | `client.features.delete(feature_id)` | Delete a feature by ID | | **Plans** | | | Manage subscription plans and pricing | | | Create | `client.plans.create(request)` | Create a new plan | | | Read | `client.plans.get(plan_id, **kwargs)` | Get a plan by ID | | | Read | `client.plans.list(**kwargs)` | List all plans | | | Update | `client.plans.update(plan_id, body)` | Update a plan | | | Delete | `client.plans.delete(plan_id)` | Delete a plan by ID | | | Other | `client.plans.publish(plan_id)` | Publish a plan | | | Other | `client.plans.archive(plan_id)` | Archive a plan version | | | Other | `client.plans.next(plan_id_or_key)` | Create new draft plan version | | **Plan Addons** | | | Manage addons assigned to plans | | | Create | `client.plan_addons.create(plan_id, body)` | Create addon assignment for plan | | | Read | `client.plan_addons.get(plan_id, plan_addon_id)` | Get addon assignment for plan | | | Read | `client.plan_addons.list(plan_id, **kwargs)` | List addon assignments for plan | | | Update | `client.plan_addons.update(plan_id, plan_addon_id, body)` | Update addon assignment for plan | | | Delete | `client.plan_addons.delete(plan_id, plan_addon_id)` | Delete addon assignment for plan | | **Addons** | | | Manage standalone addons available across plans | | | Create | `client.addons.create(request)` | Create a new addon | | | Read | `client.addons.get(addon_id, **kwargs)` | Get an addon by ID | | | Read | `client.addons.list(**kwargs)` | List all addons | | | Update | `client.addons.update(addon_id, request)` | Update an addon | | | Delete | `client.addons.delete(addon_id)` | Delete an addon by ID | | | Other | `client.addons.publish(addon_id)` | Publish an addon | | | Other | `client.addons.archive(addon_id)` | Archive an addon | | **Subscriptions** | | | Manage customer subscriptions | | | Create | `client.subscriptions.create(body)` | Create a new subscription | | | Read | `client.subscriptions.get_expanded(subscription_id, **kwargs)` | Get a subscription with expanded details | | | Update | `client.subscriptions.edit(subscription_id, body)` | Edit a subscription | | | Update | `client.subscriptions.change(subscription_id, body)` | Change a subscription | | | Update | `client.subscriptions.migrate(subscription_id, body)` | Migrate subscription to a new plan version | | | Update | `client.subscriptions.restore(subscription_id)` | Restore a canceled subscription | | | Delete | `client.subscriptions.cancel(subscription_id, body)` | Cancel a subscription | | | Delete | `client.subscriptions.delete(subscription_id)` | Delete a subscription | | | Other | `client.subscriptions.unschedule_cancelation(subscription_id)` | Unschedule a subscription cancelation | | **Subscription Addons** | | | Manage addons on subscriptions | | | Create | `client.subscription_addons.create(subscription_id, body)` | Add an addon to a subscription | | | Read | `client.subscription_addons.get(subscription_id, subscription_addon_id)` | Get a subscription addon | | | Read | `client.subscription_addons.list(subscription_id, **kwargs)` | List addons on a subscription | | | Update | `client.subscription_addons.update(subscription_id, subscription_addon_id, body)` | Update a subscription addon | | **Entitlements** | | | Admin entitlements management | | | Read | `client.entitlements.list(**kwargs)` | List all entitlements (admin) | | | Read | `client.entitlements.get(entitlement_id)` | Get an entitlement by ID | | **Entitlements V2** | | | V2 Admin entitlements management | | | Read | `client.entitlements_v2.list(**kwargs)` | List all entitlements V2 (admin) | | | Read | `client.entitlements_v2.get(entitlement_id_or_feature_key, **kwargs)` | Get an entitlement V2 by ID or feature key | | **Customer Entitlements V2** | | | Manage customer entitlements (V2) | | | Create | `client.customer_entitlements_v2.post(customer_id_or_key, body)` | Create a customer entitlement | | | Read | `client.customer_entitlements_v2.list(customer_id_or_key, **kwargs)` | List customer entitlements | | | Read | `client.customer_entitlements_v2.get(customer_id_or_key, entitlement_id_or_feature_key)` | Get a customer entitlement | | | Delete | `client.customer_entitlements_v2.delete(customer_id_or_key, entitlement_id)` | Delete a customer entitlement | | | Update | `client.customer_entitlements_v2.override(customer_id_or_key, entitlement_id_or_feature_key, override)` | Override a customer entitlement | | **Customer Entitlement V2** | | | Single customer entitlement operations (V2) | | | Read | `client.customer_entitlement_v2.get_grants(customer_id_or_key, entitlement_id_or_feature_key, **kwargs)` | List grants for a customer entitlement | | | Read | `client.customer_entitlement_v2.get_customer_entitlement_value(customer_id_or_key, entitlement_id_or_feature_key, **kwargs)` | Get customer entitlement value | | | Read | `client.customer_entitlement_v2.get_customer_entitlement_history(customer_id_or_key, entitlement_id_or_feature_key, **kwargs)` | Get customer entitlement history | | | Create | `client.customer_entitlement_v2.create_customer_entitlement_grant(customer_id_or_key, entitlement_id_or_feature_key, grant)` | Create a grant for customer entitlement | | | Update | `client.customer_entitlement_v2.reset_customer_entitlement(customer_id_or_key, entitlement_id, **kwargs)` | Reset customer entitlement usage | | **Grants** | | | Admin grants management | | | Read | `client.grants.list(**kwargs)` | List all grants (admin) | | | Delete | `client.grants.delete(grant_id)` | Delete (void) a grant | | **Grants V2** | | | V2 Admin grants management | | | Read | `client.grants_v2.list(**kwargs)` | List all grants V2 (admin) | | **Billing Profiles** | | | Manage billing profiles | | | Create | `client.billing_profiles.create(profile)` | Create a billing profile | | | Read | `client.billing_profiles.get(id)` | Get a billing profile by ID | | | Read | `client.billing_profiles.list(**kwargs)` | List billing profiles | | | Update | `client.billing_profiles.update(id, profile)` | Update a billing profile | | | Delete | `client.billing_profiles.delete(id)` | Delete a billing profile | | **Invoices** | | | Manage invoices | | | Read | `client.invoices.list(**kwargs)` | List invoices | | | Other | `client.invoices.invoice_pending_lines_action(customer_id, **kwargs)` | Invoice pending lines for customer | | **Invoice** | | | Single invoice operations | | | Read | `client.invoice.get_invoice(id, **kwargs)` | Get an invoice by ID | | | Update | `client.invoice.update_invoice(id, invoice)` | Update an invoice | | | Delete | `client.invoice.delete_invoice(id)` | Delete an invoice | | | Other | `client.invoice.advance_action(id)` | Advance invoice to next status | | | Other | `client.invoice.approve_action(id)` | Approve an invoice | | | Other | `client.invoice.retry_action(id, body)` | Retry advancing invoice after failure | | | Other | `client.invoice.void_invoice_action(id)` | Void an invoice | | | Other | `client.invoice.recalculate_tax_action(id)` | Recalculate invoice tax amounts | | | Other | `client.invoice.snapshot_quantities_action(id)` | Snapshot invoice quantities | | **Customer Invoice** | | | Customer-specific invoice operations | | | Create | `client.customer_invoice.create_pending_invoice_line(customer_id, body)` | Create pending invoice line for customer | | | Other | `client.customer_invoice.simulate_invoice(customer_id, **kwargs)` | Simulate an invoice for a customer | | **Apps** | | | Manage integrations and app installations | | | Read | `client.apps.list(**kwargs)` | List installed apps | | | Read | `client.apps.get(id)` | Get an app by ID | | | Update | `client.apps.update(id, app)` | Update an app | | | Delete | `client.apps.uninstall(id)` | Uninstall an app | | **App Stripe** | | | Stripe app integration | | | Create | `client.app_stripe.webhook(id, body)` | Handle Stripe webhook event | | | Update | `client.app_stripe.update_stripe_api_key(id, request)` | Update Stripe API key | | | Create | `client.app_stripe.create_checkout_session(body)` | Create Stripe checkout session | | **App Custom Invoicing** | | | Custom invoicing app integration | | | Other | `client.app_custom_invoicing.draft_syncronized(id, invoice_number, **kwargs)` | Notify when draft invoice synchronized | | | Other | `client.app_custom_invoicing.finalized(id, invoice_number, **kwargs)` | Notify when invoice finalized | | | Other | `client.app_custom_invoicing.payment_status(id, invoice_number, body)` | Update invoice payment status | | **Marketplace** | | | App marketplace operations | | | Read | `client.marketplace.list(**kwargs)` | List marketplace apps | | | Read | `client.marketplace.get(app_type)` | Get marketplace app | | | Read | `client.marketplace.get_o_auth2_install_url(app_type, **kwargs)` | Get OAuth2 install URL | | | Create | `client.marketplace.authorize_o_auth2_install(app_type, **kwargs)` | Authorize OAuth2 installation | | | Create | `client.marketplace.install_with_api_key(app_type, body)` | Install app with API key | | | Create | `client.marketplace.install(app_type, body)` | Install marketplace app | | **Notification Channels** | | | Manage notification channels | | | Create | `client.notification_channels.create(channel)` | Create a notification channel | | | Read | `client.notification_channels.get(channel_id)` | Get a notification channel by ID | | | Read | `client.notification_channels.list(**kwargs)` | List notification channels | | | Update | `client.notification_channels.update(channel_id, channel)` | Update a notification channel | | | Delete | `client.notification_channels.delete(channel_id)` | Delete a notification channel | | **Notification Rules** | | | Manage notification rules | | | Create | `client.notification_rules.create(rule)` | Create a notification rule | | | Read | `client.notification_rules.get(rule_id)` | Get a notification rule by ID | | | Read | `client.notification_rules.list(**kwargs)` | List notification rules | | | Update | `client.notification_rules.update(rule_id, rule)` | Update a notification rule | | | Delete | `client.notification_rules.delete(rule_id)` | Delete a notification rule | | | Other | `client.notification_rules.test(rule_id)` | Test a notification rule | | **Notification Events** | | | View notification events | | | Read | `client.notification_events.get(event_id)` | Get a notification event by ID | | | Read | `client.notification_events.list(**kwargs)` | List notification events | | **Progress** | | | Track long-running operations | | | Read | `client.progress.get_progress(id)` | Get progress of a long-running operation | | **Currencies** | | | Currency information | | | Read | `client.currencies.list_currencies()` | List all supported currencies | | **Debug** | | | Debug utilities for monitoring and troubleshooting | | | Read | `client.debug.metrics()` | Get event ingestion metrics |