120 lines
2.8 KiB
Plaintext
120 lines
2.8 KiB
Plaintext
---
|
|
title: "Aggregate Events"
|
|
openapi: "openapi POST /v1/events.aggregate"
|
|
---
|
|
|
|
import { DynamicParamField } from "/components/dynamic-param-field.jsx";
|
|
import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
|
|
import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
|
|
|
|
Aggregate usage events by time period. Returns usage totals grouped by feature and optionally by a custom property.
|
|
|
|
## Working with Properties
|
|
|
|
When tracking events, you can attach custom properties that can later be used for grouping aggregations:
|
|
|
|
```typescript
|
|
// Track an event with properties
|
|
await autumn.track({
|
|
customerId: "cus_123",
|
|
featureId: "api_calls",
|
|
value: 1,
|
|
properties: {
|
|
model: "gpt-4",
|
|
source: "api",
|
|
region: "us-east"
|
|
}
|
|
});
|
|
```
|
|
|
|
You can then aggregate events grouped by any property using the `group_by` parameter:
|
|
|
|
```typescript
|
|
const result = await autumn.events.aggregate({
|
|
customerId: "cus_123",
|
|
featureId: "api_calls",
|
|
range: "7d",
|
|
groupBy: "properties.model" // Group by the "model" property
|
|
});
|
|
```
|
|
|
|
### Special Group By Operators
|
|
|
|
In addition to custom properties, you can group by built-in columns using `$`-prefixed operators:
|
|
|
|
- `$customer_id` -- Group results by customer ID. Useful when aggregating across all customers (i.e. no `customer_id` specified).
|
|
- `$entity_id` -- Group results by entity ID. Useful for seeing usage broken down per entity.
|
|
|
|
```typescript
|
|
// Aggregate across all customers, grouped by customer
|
|
const result = await autumn.events.aggregate({
|
|
featureId: "api_calls",
|
|
range: "7d",
|
|
groupBy: "$customer_id"
|
|
});
|
|
|
|
// Aggregate for a customer, grouped by entity
|
|
const result = await autumn.events.aggregate({
|
|
customerId: "cus_123",
|
|
featureId: "api_calls",
|
|
range: "7d",
|
|
groupBy: "$entity_id"
|
|
});
|
|
```
|
|
|
|
## Response Format
|
|
|
|
The response structure changes based on whether `group_by` is provided:
|
|
|
|
### Without `group_by` (Flat Response)
|
|
|
|
When no grouping is specified, `values` contains the aggregated sum for each feature:
|
|
|
|
```json
|
|
{
|
|
"list": [
|
|
{
|
|
"period": 1762905600000,
|
|
"values": {
|
|
"api_calls": 150,
|
|
"messages": 45
|
|
}
|
|
}
|
|
],
|
|
"total": {
|
|
"api_calls": { "count": 10, "sum": 150 },
|
|
"messages": { "count": 5, "sum": 45 }
|
|
}
|
|
}
|
|
```
|
|
|
|
### With `group_by` (Grouped Response)
|
|
|
|
When grouping is specified, `values` contains the total sum while `grouped_values` breaks down values by group:
|
|
|
|
```json
|
|
{
|
|
"list": [
|
|
{
|
|
"period": 1762905600000,
|
|
"values": {
|
|
"api_calls": 150
|
|
},
|
|
"grouped_values": {
|
|
"api_calls": {
|
|
"gpt-4": 100,
|
|
"gpt-3.5": 50
|
|
}
|
|
}
|
|
}
|
|
],
|
|
"total": {
|
|
"api_calls": { "count": 10, "sum": 150 }
|
|
}
|
|
}
|
|
```
|
|
|
|
<Note>
|
|
The `grouped_values` field is only present when `group_by` is provided in the request.
|
|
</Note>
|