File size: 43,384 Bytes
048b1e8 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 | # 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 |
|