- Postman collection
- Open API spec
- Authentication
- Customers
- Accounts
- Aliases
- Event Schemas
- Usage Meters
- AddOns
- Licenses
- Feature
- Price Plans
- Settings
- Price Experimentation
- Jobs
- Event Ingestion
- Entitlements
- Event Management
- Metrics
- Credits
- Invoices
- Payments
- Wallet
- InvoiceGroups
APIs
Get Togai Metrics
Togai Metrics API allows you to fetch different metrics from Events, Usage Meters and PricePlans with multiple queryable options. A single request can query up to five metrics. Single response can contain a maximum of 300 data points.
MetricQuery: Allowed field combinations
| Metric Name | Config Key | Allowed Values | Default value | Description |
|---|---|---|---|---|
REVENUE | CURRENCY | BASE or INVOICE | BASE | currency to return the revenue in |
REVENUE_FOR_CYCLE | CURRENCY | BASE or INVOICE | BASE | currency to return the revenue in |
| Metric Name | FilterEntry Name | Allowed groupBy fields | Default Values | Allowed Values |
|---|---|---|---|---|
EVENTS | ACCOUNT_ID | ACCOUNT_ID, EVENT_STATUS, SCHEMA_NAME, | None | *<one or more valid account IDs> |
EVENTS | CUSTOMER_ID | ACCOUNT_ID, EVENT_STATUS, SCHEMA_NAME, | None | *<one or more valid customer IDs> |
EVENTS | SCHEMA_NAME | ACCOUNT_ID, EVENT_STATUS, SCHEMA_NAME, | None | *<at most one valid schema names> |
EVENTS | EVENT_STATUS | ACCOUNT_ID, EVENT_STATUS, SCHEMA_NAME, | [PROCESSED, UNPROCESSED] | oneOrMoreOf PROCESSED, UNPROCESSED, IN_PROGRESS |
USAGE | ACCOUNT_ID | ACCOUNT_ID, USAGE_METER_ID, CUSTOMER_ID | None | *<one or more valid account IDs> |
USAGE | CUSTOMER_ID | ACCOUNT_ID, USAGE_METER_ID, CUSTOMER_ID | None | *<one or more valid customer IDs> |
USAGE | USAGE_METER_ID | ACCOUNT_ID, USAGE_METER_ID, CUSTOMER_ID | None | *<one or more valid usage meter name> |
REVENUE | ACCOUNT_ID | ACCOUNT_ID, USAGE_METER_ID, CUSTOMER_ID | None | *<one or more valid account IDs> |
REVENUE | CUSTOMER_ID | ACCOUNT_ID, USAGE_METER_ID, CUSTOMER_ID | None | *<one or more valid customer IDs> |
REVENUE | USAGE_METER_ID | ACCOUNT_ID, USAGE_METER_ID, CUSTOMER_ID | None | *<one or more valid usage meter name> |
USAGE_FOR_CYCLE | ACCOUNT_ID | ACCOUNT_ID, USAGE_METER_ID, CUSTOMER_ID | None | *<one or more valid account IDs> |
USAGE_FOR_CYCLE | CUSTOMER_ID | ACCOUNT_ID, USAGE_METER_ID, CUSTOMER_ID | None | *<one or more valid customer IDs> |
USAGE_FOR_CYCLE | USAGE_METER_ID | ACCOUNT_ID, USAGE_METER_ID, CUSTOMER_ID | None | *<one or more valid usage meter name> |
REVENUE_FOR_CYCLE | ACCOUNT_ID | ACCOUNT_ID, USAGE_METER_ID, CUSTOMER_ID | None | *<one or more valid account IDs> |
REVENUE_FOR_CYCLE | CUSTOMER_ID | ACCOUNT_ID, USAGE_METER_ID, CUSTOMER_ID | None | *<one or more valid customer IDs> |
REVENUE_FOR_CYCLE | USAGE_METER_ID | ACCOUNT_ID, USAGE_METER_ID, CUSTOMER_ID | None | *<one or more valid usage meter name> |
Storage
The *_FOR_CYCLE metrics in Togai are stored against the pricing cycle start date of accounts based on their pricing schedules.
For instance, metrics of an account having a MONTHLY pricing cycle configued to invoice on 5th of every month, metrics are stored as follows.
| PricingCycleStartDate | Usage/RevenueForCycle |
|---|---|
2020-01-05T00:00:00Z | 1000 |
2020-02-05T00:00:00Z | 1200 |
2020-03-05T00:00:00Z | 1200 |
In case of changes to the plan, e.g, a different monthly plan which is configured to invoice on 1st of every month is associated to account from 2020-03-15, metrics are stored as follows.
| PricingCycleStartDate | Usage/RevenueForCycle |
|---|---|
2020-01-05T00:00:00Z | 1000 |
2020-02-05T00:00:00Z | 1200 |
2020-03-05T00:00:00Z | 1250 |
2020-03-15T00:00:00Z | 600 |
2020-04-01T00:00:00Z | 1300 |
2020-05-01T00:00:00Z | 1300 |
Querying
Now, in order to query the *_FOR_CYCLE metrics for any pricing cycle, make sure that the PricingCycleStartDate lies within startTime (inclusive) and endTime (exclusive).
Example, for metrics query with startTime as 2020-02-15T00:00:00Z and endTime as 2020-04-01T00:00:00Z results contain the data from below records.
| PricingCycleStartDate | Usage/RevenueForCycle |
|---|---|
2020-03-05T00:00:00Z | 1250 |
2020-03-15T00:00:00Z | 600 |
and not data from 2020-02-15T00:00:00Z or from 2020-04-01T00:00:00Z
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Start date time of the query (inclusive)
End date time of the query (exclusive)
Mandatory for all request. User defined ID for identifying the request for your internal reference
Define the metric you would like to get - allowed options are EVENTS - Aggregation of raw events, USAGE - Default to METER_USAGE. To be deprecated soon, METER_USAGE - Aggregated usage value from Usage meters, NAMED_LICENSE_USAGE - Aggregated usage value from Named Licenses, REVENUE - Aggregated revenue value from Pricing Plans USAGE_FOR_CYCLE - Usage in pricing cycle REVENUE_FOR_CYCLE - Revenue in pricing cycle
EVENTS, USAGE, METER_USAGE, NAMED_LICENSE_USAGE, REVENUE, USAGE_FOR_CYCLE, REVENUE_FOR_CYCLE Set the aggregation period. Allowed periods are HOUR, DAY, WEEK, MONTH
HOUR, DAY, WEEK, MONTH Group your metric with a groupBy field. Allowed fields are ACCOUNT_ID EVENT_STATUS SCHEMA_NAME USAGE_METER_ID [Use BILLABLE_ID as this will be deprecated soon...] BILLABLE_ID RAW_EVENT_STATUS Please refer the table above for the list of combinations allowed in the groupBy
Configurations. | Metric Name | Config Key | Allowed Values | Default value | Description | |-------------------|------------|-----------------|---------------|-----------------------------------| | REVENUE | CURRENCY | BASE or INVOICE | BASE | currency to return the revenue in | | REVENUE_FOR_CYCLE | CURRENCY | BASE or INVOICE | BASE | currency to return the revenue in |
Filter on specific fields. Refer possible fieldNames and fieldValues from the table above.
Response
Define the metric you would like to get - allowed options are EVENTS - Aggregation of raw events, USAGE - Default to METER_USAGE. To be deprecated soon, METER_USAGE - Aggregated usage value from Usage meters, NAMED_LICENSE_USAGE - Aggregated usage value from Named Licenses, REVENUE - Aggregated revenue value from Pricing Plans USAGE_FOR_CYCLE - Usage in pricing cycle REVENUE_FOR_CYCLE - Revenue in pricing cycle
EVENTS, USAGE, METER_USAGE, NAMED_LICENSE_USAGE, REVENUE, USAGE_FOR_CYCLE, REVENUE_FOR_CYCLE