> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexprice.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Events
> Every events command in the Flexprice CLI, with flags, required fields and examples.
## analytics
Get usage analytics
| Flag | Type | Required | Description |
| ------------------------ | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--breakdown_bucket` | boolean | | BreakdownBucket when true augments each time-series point with BucketID/PriceID and appends a BucketSummaries rollup to each item. Requires WindowSize to be set and the item to be linked to a subscription line item that has CommitmentTimeBuckets. Default: false (opt-in, backward compatible). |
| `--end_time` | string | | |
| `--external_customer_id` | string | | ExternalCustomerID is the single external customer ID. Optional when ExternalCustomerIDs is provided; required otherwise. |
| `--include_children` | boolean | | IncludeChildren when true folds child customers' usage into the single aggregated total. Default: false. |
| `--start_time` | string | | |
| `--window_size` | string | | |
These fields are nested and cannot be set with flags. Use `--edit` to fill in a pre-built request body, or `--data @file.json`.
* `expand` (array)
* `feature_ids` (array)
* `group_by` (array)
* `property_filters` (object)
* `sources` (array)
```sh theme={null}
flexprice events analytics
```
## huggingface-inference
Get Hugging Face inference data
These fields are nested and cannot be set with flags. Use `--edit` to fill in a pre-built request body, or `--data @file.json`.
* `requestIds` (array)
```sh theme={null}
flexprice events huggingface-inference
```
## ingest
Ingest event
| Flag | Type | Required | Description |
| ------------------------ | ------ | -------- | --------------------------------- |
| `--customer_id` | string | | |
| `--event_id` | string | | |
| `--event_name` | string | yes | |
| `--external_customer_id` | string | yes | |
| `--source` | string | | |
| `--timestamp` | string | | Handled separately due to parsing |
These fields are nested and cannot be set with flags. Use `--edit` to fill in a pre-built request body, or `--data @file.json`.
* `properties` (object)
```sh theme={null}
flexprice events ingest --event_name= --external_customer_id=
```
## ingest-bulk
Bulk ingest events
These fields are nested and cannot be set with flags. Use `--edit` to fill in a pre-built request body, or `--data @file.json`.
* `events` (array)
```sh theme={null}
flexprice events ingest-bulk
```
## list
List raw events
| Flag | Type | Required | Description |
| ------------------------ | ------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `--end_time` | string | | End time of the events to be fetched in ISO 8601 format Defaults to now if not provided |
| `--event_id` | string | | Event ID is the idempotency key for the event |
| `--event_name` | string | | Event name / Unique identifier for the event in your system |
| `--external_customer_id` | string | | Customer ID in your system that was sent with the event |
| `--iter_first_key` | string | | First key to iterate over the events |
| `--iter_last_key` | string | | Last key to iterate over the events |
| `--offset` | integer | | Offset to fetch the events and is set to 0 by default |
| `--order` | string | | Order by condition. Allowed values (case sensitive): asc, desc (default: desc) |
| `--page_size` | integer | | Page size to fetch the events and is set to 50 by default |
| `--sort` | string | | Sort by the field. Allowed values (case sensitive): timestamp, event\_name (default: timestamp) |
| `--source` | string | | Source to filter the events by the source |
| `--start_time` | string | | Start time of the events to be fetched in ISO 8601 format Defaults to last 7 days from now if not provided |
These fields are nested and cannot be set with flags. Use `--edit` to fill in a pre-built request body, or `--data @file.json`.
* `property_filters` (object)
```sh theme={null}
flexprice events list
```
## retrieve
Get event
```sh theme={null}
flexprice events retrieve
```
## usage
Get usage statistics
| Flag | Type | Required | Description |
| ------------------------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--aggregation_type` | string | yes | |
| `--billing_anchor` | string | | BillingAnchor enables custom monthly billing periods for usage aggregation. When to use: - WindowSize = "MONTH" AND you need custom monthly periods (not calendar months) - Subscription billing that doesn't align with calendar months - Example: Customer signed up on 15th, so billing periods are 15th to 15th When NOT to use: - WindowSize != "MONTH" (ignored for DAY, HOUR, WEEK, etc.) - Standard calendar-based billing (1st to 1st of each month) Example values: - "2024-03-05T14:30:45.123456789Z" (5th of each month at 2:30:45 PM) - "2024-01-15T00:00:00Z" (15th of each month at midnight) - "2024-02-29T12:00:00Z" (29th of each month at noon - handles leap years) |
| `--bucket_size` | string | | |
| `--customer_id` | string | | |
| `--end_time` | string | | |
| `--event_name` | string | yes | |
| `--external_customer_id` | string | | |
| `--group_by_property` | string | | GroupByProperty is the property name in event.properties to group by before aggregating. When set, aggregation is applied per unique value of this property within each bucket, then the per-group results are summed to produce the bucket total. Deprecated: prefer GroupBy \[]string{"properties."} for parity with other analytics endpoints. ToUsageParams translates this field into GroupBy when GroupBy is otherwise empty. |
| `--multiplier` | string | | |
| `--property_name` | string | | will be empty/ignored in case of COUNT |
| `--start_time` | string | | |
| `--timezone` | string | | |
| `--window_size` | string | | |
These fields are nested and cannot be set with flags. Use `--edit` to fill in a pre-built request body, or `--data @file.json`.
* `filters` (object)
* `group_by` (array)
```sh theme={null}
flexprice events usage --aggregation_type= --event_name=
```
## usage-by-meter
Get usage by meter
| Flag | Type | Required | Description |
| ------------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--billing_anchor` | string | | BillingAnchor enables custom monthly billing periods for meter usage aggregation. Usage guidelines: - Only effective when WindowSize = "MONTH" - For other window sizes (DAY, HOUR, WEEK), this field is ignored - When nil, uses standard calendar months (1st to 1st) - When provided, creates custom monthly periods (e.g., 5th to 5th) Common use cases: - Subscription billing periods that don't align with calendar months - Customer-specific billing cycles (e.g., signed up on 15th) - Multi-tenant systems with different billing anchor dates Example: If BillingAnchor = "2024-03-05T14:30:45Z" and WindowSize = "MONTH": - March period: 2024-03-05 14:30:45 to 2024-04-05 14:30:45 - April period: 2024-04-05 14:30:45 to 2024-05-05 14:30:45 |
| `--bucket_size` | string | | |
| `--customer_id` | string | | |
| `--end_time` | string | | |
| `--external_customer_id` | string | | |
| `--meter_id` | string | yes | |
| `--start_time` | string | | |
| `--timezone` | string | | |
| `--window_size` | string | | |
These fields are nested and cannot be set with flags. Use `--edit` to fill in a pre-built request body, or `--data @file.json`.
* `filters` (object)
```sh theme={null}
flexprice events usage-by-meter --meter_id=
```