Get Togai Metrics

POST

metrics

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

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request to get metrics from togai

startTime

string

required

Start date time of the query (inclusive)

Example:

"2017-07-21T00:00:00Z"

endTime

string

required

End date time of the query (exclusive)

Example:

"2017-07-21T00:00:00Z"

metricQueries

object[]

required

Object representing a single metrics query

metricQueries.id

string

required

Mandatory for all request. User defined ID for identifying the request for your internal reference

metricQueries.name

enum<string>

default:EVENTS

required

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

Available options:

EVENTS,

USAGE,

METER_USAGE,

NAMED_LICENSE_USAGE,

REVENUE,

USAGE_FOR_CYCLE,

REVENUE_FOR_CYCLE

metricQueries.aggregationPeriod

enum<string>

default:DAY

required

Set the aggregation period. Allowed periods are HOUR, DAY, WEEK, MONTH

Available options:

HOUR,

DAY,

WEEK,

MONTH

metricQueries.groupBy

string

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

metricQueries.configs

object

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

metricQueries.filters

object[]

Filter on specific fields. Refer possible fieldNames and fieldValues from the table above.

Metric Name	FilterEntry Name	Allowed groupBy fields	Default Values	Allowed Values
EVENTS	ACCOUNT_ID	ACCOUNT_ID, EVENT_STATUS, SCHEMA_NAME, RAW_EVENT_STATUS	None	*<one or more valid account IDs>
EVENTS	CUSTOMER_ID	ACCOUNT_ID, EVENT_STATUS, SCHEMA_NAME, RAW_EVENT_STATUS	None	*<one or more valid customer IDs>
EVENTS	SCHEMA_NAME	ACCOUNT_ID, EVENT_STATUS, SCHEMA_NAME, RAW_EVENT_STATUS	None	*<at most one valid schema names>
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	*<one or more valid account IDs>
USAGE	CUSTOMER_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	None	*<one or more valid customer IDs>
USAGE	USAGE_METER_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	None	*<one or more valid usage meter name>
USAGE	BILLABLE_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	None	*<one or more valid usage meter name>
REVENUE	ACCOUNT_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	None	*<one or more valid account IDs>
REVENUE	CUSTOMER_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	None	*<one or more valid customer IDs>
REVENUE	USAGE_METER_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	None	*<one or more valid usage meter name>
REVENUE	BILLABLE_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	None	*<one or more valid usage meter name>
EVENTS	ORGANIZATION_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	<From auth token>
USAGE	ORGANIZATION_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	<From auth token>
REVENUE	ORGANIZATION_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	<From auth token>
USAGE_FOR_CYCLE	ACCOUNT_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	None	*<one or more valid account IDs>
USAGE_FOR_CYCLE	CUSTOMER_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	None	*<one or more valid customer IDs>
USAGE_FOR_CYCLE	USAGE_METER_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	None	*<one or more valid usage meter name>
USAGE_FOR_CYCLE	BILLABLE_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	None	*<one or more valid usage meter name>
REVENUE_FOR_CYCLE	ACCOUNT_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	None	*<one or more valid account IDs>
REVENUE_FOR_CYCLE	CUSTOMER_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	None	*<one or more valid customer IDs>
REVENUE_FOR_CYCLE	USAGE_METER_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	None	*<one or more valid usage meter name>
REVENUE_FOR_CYCLE	BILLABLE_ID	ACCOUNT_ID, USAGE_METER_ID, BILLABLE_ID CUSTOMER_ID	None	*<one or more valid usage meter name>

Response

200

application/json

Success response

Response to GetMetrics Request

results

object[]

required

Response to GetMetrics Request

Correct an ingested event List credits

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
          ]
        }
      ]
    }
  ]
}

Introduction

APIs

MetricQuery: Allowed field combinations

Storage

Querying

Authorizations

Body

Response

Introduction

APIs

​MetricQuery: Allowed field combinations

Authorizations

Body

Response

MetricQuery: Allowed field combinations