Usage Tracking API

The Usage Tracking API helps businesses track and reconcile product usage metrics to make it easier to measure product performance, integrate usage information in lead scoring, and perform billing against contracts built with RevOps.

Why track usage with RevOps?

Business models don't stay the same, the raw data of a product's usage is what gives the flexibility to change the model over time. Running computations in realtime to analyze existing datasets, decide on pricing, and also execute existing pricing calculations requires a significant investment.

RevOps can help businesses track and reconcile usage computations and add significant time savings for engineering teams to spend on their own products.

How does it work?

  1. Collect your product metrics on any interval.
  2. Publish the data to the RevOps API.
  3. Let RevOps handle the rest!

Data Collection

RevOps usage tracking asserts the following rules:

  1. Preserves input.
  2. Allows memoizable updates to correct data.
  3. Show data provenance in computations.

Usage Tracking Endpoints

Each endpoint assumes a default base url: https://vault.revops.io/v1/

Usage Events List Resource

https://vault.revops.io/v1/usage/events

Supported Methods:

  • GET - Retrieves usage events previously recored
  • POST - Create or update a batch of metrics to be processed

API Key Accessibility

POST and GET requests can only be accessed with an API secret key.

HTTP Method Public Key Secret Key
GET N/A
POST N/A

GET USAGE EVENTS

GET /v1/usage/events

Query Parameters

Name Description
page Return results for the specified page number
pageSize The number of results to include with each page. The default is 50 and the maximum is 500.
startDate The start date for records to be included. This must be formatted YYYY-MM-DD.
endDate The end date for records to be included. This must be formatted YYYY-MM-DD.

Summary:

The UsageEvent list handler is a top-level resource that has support for bulk fetching of usage events. This handler returns paginated results and may require multiple requests to fetch all available data.

Examples:

This an example curl command fetching usage events from RevOps:

$> curl https://vault.revops.io/v1/usage/events \
        -H 'Authorization: Bearer <api_key>'

The following is an example response:

{
  "first_page_uri": "/v1/usage/events?page=0&pageSize=50",
  "next_page_uri": null,
  "page": 0,
  "page_size": 50,
  "previous_page_uri": null,
  "results": [
    {
      "id": "usage_a267b19268d845678df5728fc8e5163f",
      "uri": "/v1/usage/events/usage_a267b19268d845678df5728fc8e5163f",
      "date_submitted": "2019-08-16T22:29:35.678253+00:00",
      "event_metrics": [
        {
          "account_id": "revops-io",
          "metadata": {},
          "metric_name": "status",
          "metric_resolution": "hour",
          "metric_value": 1,
          "product": "sms-notifications",
          "sub_account_id": ""
        }
      ],
      "mode": "upsert",
      "transaction_id": "transaction_bc8d239616f34c80b54a22c976c5d4aa"
    }
  ]
}

Parameters

Name Located in Description Required Schema
body body Array of UsageEvent objects to be added for tracking and reconciliation Yes UsageEvent

Responses

Code Description
200 UsageEvent has been accepted and processed by RevOps
400 Bad request

CREATE OR UPDATE USAGE EVENTS

POST /v1/usage/events

Summary:

UsageEvents can be created or updated by sending a POST request to RevOps. The request should contain the full set of metrics to be processed by the usage tracking system.

Examples:

The following is an example curl command creating a new UsageEvent with RevOps:

$> curl -X POST https://vault.revops.io/v1/usage/events \
        -H 'Authorization: Bearer <api_key>' \
        -H 'Content-type: application/json' \
        --data \
'{
   "event_metrics" : [
      {
         "account_id" : "customer-account-id",
         "metadata" : {},
         "product" : "My Awesome Product",
         "metric_name" : "operation-in",
         "metric_value" : 10005345,
         "metric_resolution" : "day"
      }
   ],
   "mode" : "insert",
   "transaction_id" : "user-driven unique identifier"
}'

Idempotency of POST and PUT /v1/usage/events requests

Idempotent requests work by the widely adopted and circulated definitions.

Example of our definition with event_metrics:

  1. Two insert requests with the same identifier and identical metrics (JSON Payloads) are sent to the desired endpoint.
  2. The endpoint responds with the first instance processed.
  3. Duplicate requests are a no-op, so you can safely retry as many times.

RevOps uses transaction_id as an idempotency identifier to prevent users from accidentally storing duplicate records when requests are replayed through retry logic.

Challenges with Idempotency and differing datasets

A common error can occur in your development when:

  1. Two insert requests have the same identifier, but different sets of metrics.
  2. The endpoint will return an error for the second request.
{
  "error": {
    "message": "Idempotency check failed. A usage record exists for this transaction_id and it contains a different set of metrics. Send a new 'upsert' request with a new transaction_id to update existing metrics",
    "http_status": 400,
    "code": "idempotency-check-fail"
  }
}

We recommend log these as errors in your monitoring system and review them as possible incidents in your usage tracking integration. You can always reach out to help@revops.io or join our slack community for help.

Usage Events Instance Resource

https://vault.revops.io/v1/usage/events/:usage_id

Supported Methods:

  • GET - Retrieve a usage event
  • [DELETE] - Unsupported. Usage records cannot be deleted from RevOps. Existing records can be updated with an upsert request.
URL Parameters
Name Description Required Schema
id Unique identifier for the Account generated by the API. Yes string

API Key Accessibility
It is only possible to create PUT requests to create new accounts publicly. The remaining methods are only accessible on use of the secret key.

HTTP Method Public Key Secret Key
GET N/A
POST N/A
PUT

GET USAGE EVENT

GET /v1/usage/event/:usage_id

Summary:

Get a specific UsageEvent previously sent to RevOps

Responses
Code Description Schema
200 successful operation UsageEvent
400 Invalid ID supplied
404 UsageEvent record not found

DELETE USAGE EVENT

Summary:

UsageEvents sent to RevOps cannot be deleted. This best-practices approach to transactional ledgers allows us to keep a history of all operations performed and to support accurate data reconstruction.

Description:

DELETE requests to the usage event resource URL will return the following error:

{
  "error": {
    "message": "DELETE method on usage record not supported.  Send an 'upsert' request with a new transaction_id to update existing data",
    "http_status": 400,
    "code": "unsupported"
  }
}