These scenarios should give you a good starting point to understand what is possible and what you need to do. They are in no particular order and don’t build upon each other.

We are using cURL here for demo purposes, but you can use any of our SDKs for this as well.

Almost all query parameters can be combined to build powerful queries.

If you run into issues or something doesn’t seem possible, please get in touch, so we can figure it out together: support@unkey.dev

Detailed explanations about each individual parameter can be found in the api-reference.

​
User’s usage over the past 24h

Assuming you have an identity with externalId=user_123 and an API with apiId=api_123.

curl 'https://api.unkey.dev/v1/analytics.getVerifications?start=1736673687000&end=1736760087000&externalId=user_123&groupBy=hour&apiId=api_123' \
 -H 'Authorization: Bearer unkey_XXX'

This will return 24 elements, one per hour over the last 24h. Each element tells you about the outcomes of verifications in that interval.

[
  {
    "time": 1736672400000,
    "valid": 15125,
    "notFound": 0,
    "forbidden": 0,
    "usageExceeded": 1225,
    "rateLimited": 0,
    "unauthorized": 0,
    "disabled": 0,
    "insufficientPermissions": 0,
    "expired": 0,
    "total": 16350
  },
  {
    "time": 1736676000000,
    "valid": 765,
    "notFound": 0,
    "forbidden": 0,
    "usageExceeded": 0,
    "rateLimited": 0,
    "unauthorized": 0,
    "disabled": 0,
    "insufficientPermissions": 0,
    "expired": 0,
    "total": 765
  },
  ... 21 elements omited
  {
    "time": 1736755200000,
    "valid": 20016,
    "notFound": 0,
    "forbidden": 0,
    "usageExceeded": 0,
    "rateLimited": 0,
    "unauthorized": 0,
    "disabled": 0,
    "insufficientPermissions": 0,
    "expired": 51,
    "total": 20067
  }
]

​
Daily usage of a user per key in the last month

Assuming you have an identity with externalId=user_123 and an API with apiId=api_123.

curl 'https://api.unkey.dev/v1/analytics.getVerifications?start=1734168087000&end=1736760087000&externalId=user_123&groupBy=key&groupBy=day&apiId=api_123' \
 -H 'Authorization: Bearer unkey_XXX'

This returns 1 element per active key per day and includes the keyId.

[
  // ...
  {
    "time": 1736726400000,
    "valid": 13,
    "notFound": 0,
    "forbidden": 0,
    "usageExceeded": 0,
    "rateLimited": 10,
    "unauthorized": 0,
    "disabled": 0,
    "insufficientPermissions": 0,
    "expired": 0,
    "total": 23,
    "keyId": "key_2zeYsLbpULnEUsvYeFGMeJzACp4j"
  },
  {
    "time": 1736726400000,
    "valid": 5,
    "notFound": 0,
    "forbidden": 0,
    "usageExceeded": 6,
    "rateLimited": 0,
    "unauthorized": 0,
    "disabled": 0,
    "insufficientPermissions": 0,
    "expired": 0,
    "total": 11,
    "keyId": "key_2zeViCGkJpu5zQ8G12jcBoXWy4KH"
  }
]

​
Total usage per month for an identity

Assuming you have an identity with externalId=user_123 and an API with apiId=api_123. You should set your start to the beginning of the month and end to now or end of the month.

curl 'https://api.unkey.dev/v1/analytics.getVerifications?start=1734168087000&end=1736760087000&externalId=user_123&groupBy=month&apiId=api_123' \
 -H 'Authorization: Bearer unkey_XXX'

This returns one element per month.

[
  {
    "time": 1733011200000,
    "valid": 1356136098,
    "notFound": 0,
    "forbidden": 0,
    "usageExceeded": 0,
    "rateLimited": 925255,
    "unauthorized": 0,
    "disabled": 0,
    "insufficientPermissions": 0,
    "expired": 0,
    "total": 1357061353
  }
]

​
Showing usage in the current billing period

If you want to show a guage or similar to your user about their consumption in the current billing period.

curl 'https://api.unkey.dev/v1/analytics.getVerifications?start=1734168087000&end=1736760087000&externalId=user_123&groupBy=day&apiId=api_123' \
 -H 'Authorization: Bearer unkey_XXX'

This will return one element per day, which you can either display in a chart, or sum up to have a total value.

[
  // ...
 {
   "time": 1736553600000,
   "valid": 98267,
   "notFound": 0,
   "forbidden": 0,
   "usageExceeded": 0,
   "rateLimited": 6816,
   "unauthorized": 0,
   "disabled": 0,
   "insufficientPermissions": 0,
   "expired": 0,
   "total": 105083
 },
 {
   "time": 1736640000000,
   "valid": 20125,
   "notFound": 0,
   "forbidden": 0,
   "usageExceeded": 0,
   "rateLimited": 2525,
   "unauthorized": 0,
   "disabled": 6261,
   "insufficientPermissions": 0,
   "expired": 0,
   "total": 28911
 }
]

​
Internal dashboard showing top 10 users by API usage over the past 30 days

curl 'https://api.unkey.dev/v1/analytics.getVerifications?start=1734168087000&end=1736760087000&orderBy=total&order=desc&limit=10&groupBy=identity&apiId=api_123' \
 -H 'Authorization: Bearer unkey_XXX'

Returns 10 elements, ordered from most total verifications to least. Each element includes the identityId as well as the externalId for your reference.

[
  {
    "identity": { "id": "id_123", "externalId": "user_123"},
    "valid": 54,
    "notFound": 0,
    "forbidden": 3,
    "usageExceeded": 6,
    "rateLimited": 10,
    "unauthorized": 0,
    "disabled": 0,
    "insufficientPermissions": 0,
    "expired": 0,
    "total": 73
  },
  {
    "identity": { "id": "id_456", "externalId": "user_6dg"},
    "valid": 24,
    "notFound": 0,
    "forbidden": 1,
    "usageExceeded": 32,
    "rateLimited": 10,
    "unauthorized": 0,
    "disabled": 0,
    "insufficientPermissions": 0,
    "expired": 0,
    "total": 67
  },
  ...
]

​
Filter by tags

Find out how many verifications were done, where the tag myTag was specified. You can combine this with other parameters to group by days for example.

You can provide multiple tags by providing them as separate query paramters: ?tag=myTag&tag=myOthertag. Filtering multiple tags is a logical OR. The result includes all verifications where at least one of the filtered tags was specified.

curl 'https://api.unkey.dev/v1/analytics.getVerifications?start=1734168087000&end=1736760087000&tag=myTag&apiId=api_123' \
 -H 'Authorization: Bearer unkey_XXX'

This returns 1 element, a sum of all verifications in the selected time, where the tag myTag was specified.


[
  {
    "valid": 5,
    "notFound": 0,
    "forbidden": 0,
    "usageExceeded": 0,
    "rateLimited": 0,
    "unauthorized": 0,
    "disabled": 0,
    "insufficientPermissions": 0,
    "expired": 0,
    "total": 5
  }
]

​
Filter by key

This only includes verifications of a specific key. You can provide multiple keyIds to filter verifications of any one of those keys.

curl 'https://api.unkey.dev/v1/analytics.getVerifications?start=1734168087000&end=1736760087000&keyId=key_123&apiId=api_123' \
 -H 'Authorization: Bearer unkey_XXX'

[
  {
    "valid": 14,
    "notFound": 0,
    "forbidden": 0,
    "usageExceeded": 0,
    "rateLimited": 10,
    "unauthorized": 0,
    "disabled": 0,
    "insufficientPermissions": 0,
    "expired": 0,
    "total": 24
  }
]

​
Grouping by tags

To understand usage across your tags, you can group by tags, breaking down all verifications and summing them up per tag combination.

Note this is plural: &groupBy=tags.

curl 'https://api.unkey.dev/v1/analytics.getVerifications?start=1734168087000&end=1736760087000&groupBy=tags&apiId=api_123' \
 -H 'Authorization: Bearer unkey_XXX'

You’ll receive an array of elements. Each element corresponds to one tag combination.

[
  {
    "valid": 50,
    "notFound": 0,
    "forbidden": 3,
    "usageExceeded": 6,
    "rateLimited": 10,
    "unauthorized": 0,
    "disabled": 0,
    "insufficientPermissions": 0,
    "expired": 0,
    "total": 69,
    "tags": [] // these did not have tags specified
  },
  {
    "valid": 1,
    "notFound": 0,
    "forbidden": 0,
    "usageExceeded": 0,
    "rateLimited": 0,
    "unauthorized": 0,
    "disabled": 0,
    "insufficientPermissions": 0,
    "expired": 0,
    "total": 1,
    "tags": [
      "a",
      "b"
    ]
  },
  {
    "valid": 2,
    "notFound": 0,
    "forbidden": 0,
    "usageExceeded": 0,
    "rateLimited": 0,
    "unauthorized": 0,
    "disabled": 0,
    "insufficientPermissions": 0,
    "expired": 0,
    "total": 2,
    "tags": [
      "a",
      "c"
    ]
  },
  {
    "valid": 2,
    "notFound": 0,
    "forbidden": 0,
    "usageExceeded": 0,
    "rateLimited": 0,
    "unauthorized": 0,
    "disabled": 0,
    "insufficientPermissions": 0,
    "expired": 0,
    "total": 2,
    "tags": [
      "a"
    ]
  }
]

​
Breakdown by individual tag

If you want to see usage for an individual tag, regardless of combination with other tags, you can group by tag.

Note this is singular &groupBy=tag.

curl 'https://api.unkey.dev/v1/analytics.getVerifications?start=1734168087000&end=1736760087000&groupBy=tag&apiId=api_123' \
 -H 'Authorization: Bearer unkey_XXX'

You’ll receive one element per unique tag.

[
  {
    "valid": 1,
    "notFound": 0,
    "forbidden": 0,
    "usageExceeded": 0,
    "rateLimited": 0,
    "unauthorized": 0,
    "disabled": 0,
    "insufficientPermissions": 0,
    "expired": 0,
    "total": 1,
    "tag": "b"
  },
  {
    "valid": 2,
    "notFound": 0,
    "forbidden": 0,
    "usageExceeded": 0,
    "rateLimited": 0,
    "unauthorized": 0,
    "disabled": 0,
    "insufficientPermissions": 0,
    "expired": 0,
    "total": 2,
    "tag": "c"
  },
  {
    "valid": 5,
    "notFound": 0,
    "forbidden": 0,
    "usageExceeded": 0,
    "rateLimited": 0,
    "unauthorized": 0,
    "disabled": 0,
    "insufficientPermissions": 0,
    "expired": 0,
    "total": 5,
    "tag": "a"
  }
]

Was this page helpful?

Suggest editsRaise issue
OverviewVercel