- 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.
curl --request POST \
--url https://api.togai.com/metrics \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"startTime": "2017-07-21T00:00:00Z",
"endTime": "2017-07-22T00:00:00Z",
"metricQueries": [
{
"id": "m1",
"name": "EVENTS",
"aggregationPeriod": "DAY",
"filters": [
{
"fieldName": "ACCOUNT_ID",
"fieldValues": [
"account#1"
]
},
{
"fieldName": "CUSTOMER_ID",
"fieldValues": [
"customer#1"
]
},
{
"fieldName": "EVENT_STATUS",
"fieldValues": [
"PROCESSED"
]
}
]
},
{
"id": "m2",
"name": "USAGE",
"aggregationPeriod": "MONTH",
"filters": [
{
"fieldName": "CUSTOMER_ID",
"fieldValues": [
"customer#1"
]
}
]
}
]
}'{
"results": [
{
"id": "m1",
"name": "EVENTS",
"data": [
{
"timestamps": [
"2017-07-21T00:00:00Z",
"2017-07-22T00:00:00Z"
],
"metricValues": [
53,
32
]
}
]
},
{
"id": "m2",
"name": "USAGE",
"data": [
{
"timestamps": [
"2017-07-01T00:00:00Z"
],
"metricValues": [
123.45
]
}
]
}
]
}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 - Aggregated usage value from Usage meters, REVENUE - Aggregated revenue value from Pricing Plans USAGE_FOR_CYCLE - Usage in pricing cycle REVENUE_FOR_CYCLE - Revenue in pricing cycle
EVENTS, 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 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 - Aggregated usage value from Usage meters, REVENUE - Aggregated revenue value from Pricing Plans USAGE_FOR_CYCLE - Usage in pricing cycle REVENUE_FOR_CYCLE - Revenue in pricing cycle
EVENTS, USAGE, REVENUE, USAGE_FOR_CYCLE, REVENUE_FOR_CYCLE curl --request POST \
--url https://api.togai.com/metrics \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"startTime": "2017-07-21T00:00:00Z",
"endTime": "2017-07-22T00:00:00Z",
"metricQueries": [
{
"id": "m1",
"name": "EVENTS",
"aggregationPeriod": "DAY",
"filters": [
{
"fieldName": "ACCOUNT_ID",
"fieldValues": [
"account#1"
]
},
{
"fieldName": "CUSTOMER_ID",
"fieldValues": [
"customer#1"
]
},
{
"fieldName": "EVENT_STATUS",
"fieldValues": [
"PROCESSED"
]
}
]
},
{
"id": "m2",
"name": "USAGE",
"aggregationPeriod": "MONTH",
"filters": [
{
"fieldName": "CUSTOMER_ID",
"fieldValues": [
"customer#1"
]
}
]
}
]
}'{
"results": [
{
"id": "m1",
"name": "EVENTS",
"data": [
{
"timestamps": [
"2017-07-21T00:00:00Z",
"2017-07-22T00:00:00Z"
],
"metricValues": [
53,
32
]
}
]
},
{
"id": "m2",
"name": "USAGE",
"data": [
{
"timestamps": [
"2017-07-01T00:00:00Z"
],
"metricValues": [
123.45
]
}
]
}
]
}