Consumption based billing for APIs is getting more and more popular, but it’s tedious to build in house. For low frequency events, it’s quite possible to emit usage events directly to Stripe or similar, but this becomes very noisy quickly. Furthermore if you want to build end-user facing or internal analytics, you need to be able to query the events from Stripe, which often does not provide the granularity required.

Most teams end up without end-user facing analytics, or build their own system to store and query usage metrics.

Since Unkey already stores and aggregates verification events by time, outcome and identity, we can offer this data via an API.

​
Available data

Unkey stores an event for every single verification, the relevent fields are described below:

DataTypeExplanation
request_idStringEach request has a unique id, making it possible to retrieve later.
timeInt64A unix milli timestamp.
key_space_idStringEach workspace may have multiple key spaces. Each API you create has its own keyspace.
key_idStringThe individual key being verified.
outcomeStringThe outcome of the verification. VALID, RATE_LIMITED etc.
identity_idStringThe identity connected to this key.
tagsArray(String)Arbitrary tags you may add during the verification to filter later.

We can return this data aggregated by hour, day, month, tag, tags, identity, key and outcome. As well as filter by identity_id, key_space_id, key_id, tags, outcome, start and end time.

​
Example

For an internal dashboard you want to find the top 5 users of a specific endpoint. In order to let Unkey know about the endpoint, you specify it as a tag when verifying keys:

Tagging a verification
curl -XPOST 'https://api.unkey.dev/v1/keys.verifyKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "<API_KEY>",
    "apiId": "api_<API_ID>",
    "tags": [ "path=/my/endpoint" ],
  }'

You can now query api.unkey.dev/v1/analytics.getVerifications via query parameters. While we can’t provide raw SQL access, we wanted to stay as close to SQL semantics as possible, so you didn’t need to learn a new concept and to keep the translation layer simple.

NameValueExplanation
start1733749385000A unix milli timestamp to limit the query to a specific time frame.
end1736431397000A unix milli timestamp to limit the query to a specific time frame.
apiIdapi_262b3iR7gkmP7aUyZ24uihcijsCeThe API ID to filter keys.
groupByidentityWe’re not interested in individual keys, but the user/org.
orderBytotalWe want to see the most active users, by how many verifications they’re doing.
orderdescWe’re ordering from most active to least active user.
limit5Only return the top 5.

Below is a curl command putting everythign together:

curl 'https://api.unkey.dev/v1/analytics.getVerifications?start=1733749385000&end=1736431397000&apiId=api_262b3iR7gkmP7aUyZ24uihcijsCe&groupBy=identity&orderBy=total&order=desc&limit=5' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <UNKEY_ROOT_KEY>'

You’ll receive a json response with a breakdown of each outcome, per identity ordered by total.

Was this page helpful?

Suggest editsRaise issue
Event TypesVercel