cURL
curl --request POST \
--url https://api.tirdad.ai/v1/events/usage \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"event_name": "api_request",
"billing_anchor": "2024-03-05T14:30:45.123456789Z",
"customer_id": "customer456",
"end_time": "2024-03-20T00:00:00Z",
"external_customer_id": "customer456",
"filters": {},
"group_by": [
"<string>"
],
"group_by_property": "<string>",
"multiplier": "<string>",
"property_name": "request_size",
"start_time": "2024-03-13T00:00:00Z",
"timezone": "<string>"
}
'from tirdad_sdk import Tirdad
from tirdad_sdk.utils import parse_datetime
with Tirdad(
api_key_auth="<YOUR_API_KEY_HERE>",
) as f_client:
res = f_client.events.get_usage_statistics(aggregation_type="COUNT_UNIQUE", event_name="api_request", billing_anchor=parse_datetime("2024-03-05T14:30:45.123456789Z"), customer_id="customer456", end_time=parse_datetime("2024-03-20T00:00:00Z"), external_customer_id="customer456", property_name="request_size", start_time=parse_datetime("2024-03-13T00:00:00Z"))
# Handle response
print(res)import { Tirdad } from "@tirdad/sdk";
const tirdad = new Tirdad({
apiKeyAuth: "<YOUR_API_KEY_HERE>",
});
async function run() {
const result = await tirdad.events.getUsageStatistics({
aggregationType: "COUNT_UNIQUE",
billingAnchor: new Date("2024-03-05T14:30:45.123456789Z"),
customerId: "customer456",
endTime: new Date("2024-03-20T00:00:00Z"),
eventName: "api_request",
externalCustomerId: "customer456",
propertyName: "request_size",
startTime: new Date("2024-03-13T00:00:00Z"),
});
console.log(result);
}
run();package main
import(
"context"
tirdad "github.com/tirdad-billing/go-sdk/v2"
"github.com/tirdad-billing/go-sdk/v2/models/types"
"github.com/tirdad-billing/go-sdk/v2/types"
"log"
)
func main() {
ctx := context.Background()
s := tirdad.New(
tirdad.WithSecurity("<YOUR_API_KEY_HERE>"),
)
res, err := s.Events.GetUsageStatistics(ctx, types.GetUsageRequest{
AggregationType: types.AggregationTypeCountUnique,
BillingAnchor: types.MustNewTimeFromString("2024-03-05T14:30:45.123456789Z"),
CustomerID: tirdad.Pointer("customer456"),
EndTime: types.MustNewTimeFromString("2024-03-20T00:00:00Z"),
EventName: "api_request",
ExternalCustomerID: tirdad.Pointer("customer456"),
PropertyName: tirdad.Pointer("request_size"),
StartTime: types.MustNewTimeFromString("2024-03-13T00:00:00Z"),
})
if err != nil {
log.Fatal(err)
}
if res.GetUsageResponse != nil {
// handle response
}
}{
"event_name": "<string>",
"results": [
{
"value": 123,
"window_size": "<string>"
}
],
"type": "COUNT",
"value": 123
}{
"code": "http_client_error",
"http_status_code": 123,
"message": "<string>"
}{
"code": "http_client_error",
"http_status_code": 123,
"message": "<string>"
}Events
Get usage statistics
Use when building usage reports or dashboards across events. Supports filters and grouping; defaults to last 7 days if no range provided.
POST
/
events
/
usage
cURL
curl --request POST \
--url https://api.tirdad.ai/v1/events/usage \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"event_name": "api_request",
"billing_anchor": "2024-03-05T14:30:45.123456789Z",
"customer_id": "customer456",
"end_time": "2024-03-20T00:00:00Z",
"external_customer_id": "customer456",
"filters": {},
"group_by": [
"<string>"
],
"group_by_property": "<string>",
"multiplier": "<string>",
"property_name": "request_size",
"start_time": "2024-03-13T00:00:00Z",
"timezone": "<string>"
}
'from tirdad_sdk import Tirdad
from tirdad_sdk.utils import parse_datetime
with Tirdad(
api_key_auth="<YOUR_API_KEY_HERE>",
) as f_client:
res = f_client.events.get_usage_statistics(aggregation_type="COUNT_UNIQUE", event_name="api_request", billing_anchor=parse_datetime("2024-03-05T14:30:45.123456789Z"), customer_id="customer456", end_time=parse_datetime("2024-03-20T00:00:00Z"), external_customer_id="customer456", property_name="request_size", start_time=parse_datetime("2024-03-13T00:00:00Z"))
# Handle response
print(res)import { Tirdad } from "@tirdad/sdk";
const tirdad = new Tirdad({
apiKeyAuth: "<YOUR_API_KEY_HERE>",
});
async function run() {
const result = await tirdad.events.getUsageStatistics({
aggregationType: "COUNT_UNIQUE",
billingAnchor: new Date("2024-03-05T14:30:45.123456789Z"),
customerId: "customer456",
endTime: new Date("2024-03-20T00:00:00Z"),
eventName: "api_request",
externalCustomerId: "customer456",
propertyName: "request_size",
startTime: new Date("2024-03-13T00:00:00Z"),
});
console.log(result);
}
run();package main
import(
"context"
tirdad "github.com/tirdad-billing/go-sdk/v2"
"github.com/tirdad-billing/go-sdk/v2/models/types"
"github.com/tirdad-billing/go-sdk/v2/types"
"log"
)
func main() {
ctx := context.Background()
s := tirdad.New(
tirdad.WithSecurity("<YOUR_API_KEY_HERE>"),
)
res, err := s.Events.GetUsageStatistics(ctx, types.GetUsageRequest{
AggregationType: types.AggregationTypeCountUnique,
BillingAnchor: types.MustNewTimeFromString("2024-03-05T14:30:45.123456789Z"),
CustomerID: tirdad.Pointer("customer456"),
EndTime: types.MustNewTimeFromString("2024-03-20T00:00:00Z"),
EventName: "api_request",
ExternalCustomerID: tirdad.Pointer("customer456"),
PropertyName: tirdad.Pointer("request_size"),
StartTime: types.MustNewTimeFromString("2024-03-13T00:00:00Z"),
})
if err != nil {
log.Fatal(err)
}
if res.GetUsageResponse != nil {
// handle response
}
}{
"event_name": "<string>",
"results": [
{
"value": 123,
"window_size": "<string>"
}
],
"type": "COUNT",
"value": 123
}{
"code": "http_client_error",
"http_status_code": 123,
"message": "<string>"
}{
"code": "http_client_error",
"http_status_code": 123,
"message": "<string>"
}Body
application/json
Request body
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)
Example:
"2024-03-05T14:30:45.123456789Z"
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.