> ## Documentation Index
> Fetch the complete documentation index at: https://docs.togai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 | \*\ |
| `EVENTS` | `CUSTOMER_ID` | `ACCOUNT_ID`, `EVENT_STATUS`, `SCHEMA_NAME`, | None | \*\ |
| `EVENTS` | `SCHEMA_NAME` | `ACCOUNT_ID`, `EVENT_STATUS`, `SCHEMA_NAME`, | None | \*\ |
| `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 | \*\ |
| `USAGE` | `CUSTOMER_ID` | `ACCOUNT_ID`, `USAGE_METER_ID`, `CUSTOMER_ID` | None | \*\ |
| `USAGE` | `USAGE_METER_ID` | `ACCOUNT_ID`, `USAGE_METER_ID`, `CUSTOMER_ID` | None | \*\ |
| `REVENUE` | `ACCOUNT_ID` | `ACCOUNT_ID`, `USAGE_METER_ID`, `CUSTOMER_ID` | None | \*\ |
| `REVENUE` | `CUSTOMER_ID` | `ACCOUNT_ID`, `USAGE_METER_ID`, `CUSTOMER_ID` | None | \*\ |
| `REVENUE` | `USAGE_METER_ID` | `ACCOUNT_ID`, `USAGE_METER_ID`, `CUSTOMER_ID` | None | \*\ |
| `USAGE_FOR_CYCLE` | `ACCOUNT_ID` | `ACCOUNT_ID`, `USAGE_METER_ID`, `CUSTOMER_ID` | None | \*\ |
| `USAGE_FOR_CYCLE` | `CUSTOMER_ID` | `ACCOUNT_ID`, `USAGE_METER_ID`, `CUSTOMER_ID` | None | \*\ |
| `USAGE_FOR_CYCLE` | `USAGE_METER_ID` | `ACCOUNT_ID`, `USAGE_METER_ID`, `CUSTOMER_ID` | None | \*\ |
| `REVENUE_FOR_CYCLE` | `ACCOUNT_ID` | `ACCOUNT_ID`, `USAGE_METER_ID`, `CUSTOMER_ID` | None | \*\ |
| `REVENUE_FOR_CYCLE` | `CUSTOMER_ID` | `ACCOUNT_ID`, `USAGE_METER_ID`, `CUSTOMER_ID` | None | \*\ |
| `REVENUE_FOR_CYCLE` | `USAGE_METER_ID` | `ACCOUNT_ID`, `USAGE_METER_ID`, `CUSTOMER_ID` | None | \*\ |
***
#### 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`
## OpenAPI
````yaml post /metrics
openapi: 3.0.3
info:
version: '1.0'
title: Togai Apis
contact:
email: engg@togai.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
description: APIs for Togai App
servers:
- description: Api endpoint
url: https://api.togai.com/
- description: Sandbox api endpoint
url: https://sandbox-api.togai.com/
security:
- bearerAuth: []
tags:
- name: Customers
description: Customer level calls
- name: Accounts
description: Account level calls
- name: Event Schemas
description: Event Schema level calls
- name: Usage Meters
description: Usage Meter level calls
- name: Price Plans
description: (DEPRECATED) Price Plan level calls
- name: PricePlanV2
description: Price Plan V2 level calls
- name: Schedules
description: Account Schedule level calls
- name: Pricing Rules
description: Pricing Rules level calls
- name: Settings
description: Settings
- name: Price Experimentation
description: Price Experimentation apis
- name: InvoiceGroups
description: Invoice Group level calls
- name: Organization
description: Organization level calls
- name: FileStorage
description: File Storage level calls
- name: Aliases
description: Alias level calls
- name: Reports
description: Report level calls
- name: ReportTemplates
description: Report Template level calls
- name: Customer Portal
description: Portal level calls
- name: Alerts
description: Alert level calls
- name: Event Management
description: APIs for getting events ingested in Togai
externalDocs:
description: docs
url: https://togai.com/docs/billing/events
- name: Metrics
description: APIs for getting Togai metrics
externalDocs:
description: docs
url: https://togai.com/docs/metrics
- name: Licenses
description: APIs for getting or updating license records in Togai
- name: Entitlements
description: APIs related to entitlements
- name: Invoices
description: Invoices API
- name: Credits
description: Credits API
- name: Wallet
description: Wallet API
- name: InvoiceTemplates
description: InvoiceTemplates API
- name: InvoiceSequence
description: InvoiceSequence API
- name: Payments
description: Payments API
- name: Authentication
description: Authentication API
externalDocs:
description: Find out more about Togai
url: https://docs.togai.com/docs
paths:
/metrics:
post:
tags:
- Metrics
summary: Get Togai Metrics
description: >
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.
operationId: getMetrics
requestBody:
$ref: '#/components/requestBodies/GetMetricsRequest'
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/GetMetricsResponse'
examples:
GetMetricsResponse:
$ref: '#/components/examples/GetMetricsResponse'
'400':
description: Bad request. Please check the response message for failure details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: >-
Credential is not valid. Please check the response message for
failure details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Credential does not have access to get metrics.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: >-
Request throttled. Please check the response message on the failure
details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
default:
$ref: '#/components/responses/ErrorResponse'
components:
requestBodies:
GetMetricsRequest:
content:
application/json:
schema:
$ref: '#/components/schemas/GetMetricsRequest'
examples:
GetMetricsRequest:
value:
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
schemas:
GetMetricsResponse:
type: object
description: Response to GetMetrics Request
additionalProperties: false
required:
- results
properties:
results:
type: array
items:
$ref: '#/components/schemas/MetricQueryResponse'
ErrorResponse:
type: object
additionalProperties: false
required:
- message
properties:
message:
type: string
description: error description
maxLength: 500
GetMetricsRequest:
type: object
description: Request to get metrics from togai
additionalProperties: false
required:
- startTime
- endTime
- metricQueries
properties:
startTime:
type: string
format: date-time
description: Start date time of the query (inclusive)
example: '2017-07-21T00:00:00Z'
endTime:
type: string
format: date-time
description: End date time of the query (exclusive)
example: '2017-07-21T00:00:00Z'
metricQueries:
type: array
items:
$ref: '#/components/schemas/MetricQuery'
uniqueItems: true
MetricQueryResponse:
type: object
description: Response to GetMetrics Request
additionalProperties: false
required:
- id
- name
- data
properties:
id:
type: string
name:
$ref: '#/components/schemas/MetricName'
data:
type: array
items:
$ref: '#/components/schemas/MetricDataPoints'
MetricQuery:
type: object
description: Object representing a single metrics query
additionalProperties: false
required:
- id
- name
- aggregationPeriod
properties:
id:
type: string
description: >
Mandatory for all request.
User defined ID for identifying the request for your internal
reference
name:
$ref: '#/components/schemas/MetricName'
aggregationPeriod:
type: string
description: >-
Set the aggregation period. Allowed periods are HOUR, DAY, WEEK,
MONTH
enum:
- HOUR
- DAY
- WEEK
- MONTH
default: DAY
groupBy:
type: string
description: >
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
configs:
description: >
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 |
additionalProperties:
type: string
filters:
type: array
description: |
Filter on specific fields.
Refer possible fieldNames and fieldValues from the table above.
minItems: 1
maxItems: 5
items:
type: object
title: MetricQueryFilterEntry
description: >
| Metric Name | FilterEntry Name | Allowed groupBy
fields | Default
Values | Allowed
Values |
|-------------------|------------------|---------------------------------------------------------------------|--------------------------|-----------------------------------------------------------------|
| EVENTS | ACCOUNT_ID | ACCOUNT_ID, EVENT_STATUS,
SCHEMA_NAME, RAW_EVENT_STATUS |
None | *\ |
| EVENTS | CUSTOMER_ID | ACCOUNT_ID, EVENT_STATUS,
SCHEMA_NAME, RAW_EVENT_STATUS |
None | *\ |
| EVENTS | SCHEMA_NAME | ACCOUNT_ID, EVENT_STATUS,
SCHEMA_NAME, RAW_EVENT_STATUS |
None | *\ |
| EVENTS | EVENT_STATUS | ACCOUNT_ID, EVENT_STATUS,
SCHEMA_NAME, RAW_EVENT_STATUS | [PROCESSED,
UNPROCESSED] | oneOrMoreOf PROCESSED, UNPROCESSED, IN_PROGRESS,
IngestionStatus|
| USAGE | ACCOUNT_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
None | *\ |
| USAGE | CUSTOMER_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
None | *\ |
| USAGE | USAGE_METER_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
None | *\ |
| USAGE | BILLABLE_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
None | *\ |
| REVENUE | ACCOUNT_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
None | *\ |
| REVENUE | CUSTOMER_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
None | *\ |
| REVENUE | USAGE_METER_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
None | *\ |
| REVENUE | BILLABLE_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
None | *\ |
| EVENTS | ORGANIZATION_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
|
|
| USAGE | ORGANIZATION_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
|
|
| REVENUE | ORGANIZATION_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
|
|
| USAGE_FOR_CYCLE | ACCOUNT_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
None | *\ |
| USAGE_FOR_CYCLE | CUSTOMER_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
None | *\ |
| USAGE_FOR_CYCLE | USAGE_METER_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
None | *\ |
| USAGE_FOR_CYCLE | BILLABLE_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
None | *\ |
| REVENUE_FOR_CYCLE | ACCOUNT_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
None | *\ |
| REVENUE_FOR_CYCLE | CUSTOMER_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
None | *\ |
| REVENUE_FOR_CYCLE | USAGE_METER_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
None | *\ |
| REVENUE_FOR_CYCLE | BILLABLE_ID | ACCOUNT_ID,
USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID |
None | *\ |
additionalProperties: false
required:
- fieldName
- fieldValues
properties:
fieldName:
type: string
example: ACCOUNT_ID
fieldValues:
type: array
items:
type: string
example: account#1
MetricName:
type: string
description: |
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
enum:
- EVENTS
- USAGE
- METER_USAGE
- NAMED_LICENSE_USAGE
- REVENUE
- USAGE_FOR_CYCLE
- REVENUE_FOR_CYCLE
default: EVENTS
MetricDataPoints:
type: object
additionalProperties: false
required:
- timestamps
- metricValues
properties:
groupedBy:
title: MetricDataPointsGroupedBy
type: object
required:
- fieldName
- fieldValue
properties:
fieldName:
type: string
fieldValue:
type: string
timestamps:
type: array
items:
type: string
format: date-time
maxItems: 300
metricValues:
type: array
items:
type: number
maxItems: 300
examples:
GetMetricsResponse:
summary: example get metrics response
value:
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
responses:
ErrorResponse:
description: Error response
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ErrorResponse:
summary: Error message
value:
message:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: Bearer
````