feat: analytics

apps/dashboard/app/(app)/[workspaceSlug]/apis/[apiId]/settings/components/copy-key-space-id.tsx

@@ -0,0 +1,25 @@
+import { SettingCard } from "@unkey/ui";
+import { CopyButton } from "@unkey/ui";
+
+export const CopyKeySpaceId = ({ keySpaceId }: { keySpaceId: string }) => {
+  return (
+    <SettingCard
+      title={"KeySpace ID"}
+      description={<div className="max-w-[380px]">Identifier for the underlying keyspace.</div>}
+      border="bottom"
+      contentWidth="w-full lg:w-[420px] justify-end"
+    >
+      {/* TODO: make this a Code component in UI for CopyKeys with optional hidden button like in Code.*/}
+      <div className="flex flex-row justify-end items-center">
+        <div
+          className={
+            "flex flex-row justify-between min-w-[327px] pl-4 pr-2 py-1.5 bg-gray-2 dark:bg-black border rounded-lg border-grayA-5"
+          }
+        >
+          <div className="text-sm text-gray-11">{keySpaceId}</div>
+          <CopyButton value={keySpaceId} variant="ghost" toastMessage={keySpaceId} />
+        </div>
+      </div>
+    </SettingCard>
+  );
+};

apps/dashboard/app/(app)/[workspaceSlug]/apis/[apiId]/settings/components/settings-client.tsx

@@ -2,6 +2,7 @@
 
 import { trpc } from "@/lib/trpc/client";
 import { CopyApiId } from "./copy-api-id";
+import { CopyKeySpaceId } from "./copy-key-space-id";
 import { DefaultBytes } from "./default-bytes";
 import { DefaultPrefix } from "./default-prefix";
 import { DeleteApi } from "./delete-api";
@@ -62,6 +63,7 @@ export const SettingsClient = ({ apiId }: { apiId: string }) => {
           <div>
             <UpdateApiName api={api} />
             <CopyApiId apiId={api.id} />
+            <CopyKeySpaceId keySpaceId={keyAuth.id} />
           </div>
           <div>
             <DefaultBytes keyAuth={keyAuthForComponents} apiId={api.id} />

apps/dashboard/app/(app)/[workspaceSlug]/settings/root-keys/[keyId]/permissions/permissions.ts

@@ -25,6 +25,10 @@ export const workspacePermissions = {
       description: "Delete apis in this workspace.",
       permission: "api.*.delete_api",
     },
+    read_analytics: {
+      description: "Query analytics data for any API in this workspace using SQL.",
+      permission: "api.*.read_analytics",
+    },
   },
   Keys: {
     verify_key: {
@@ -170,6 +174,10 @@ export function apiPermissions(apiId: string): {
         description: "Update this API.",
         permission: `api.${apiId}.update_api`,
       },
+      read_analytics: {
+        description: "Query analytics data for this API using SQL.",
+        permission: `api.${apiId}.read_analytics`,
+      },
     },
     Keys: {
       verify_key: {

apps/dashboard/app/(app)/[workspaceSlug]/settings/root-keys/components/root-key/permissions.ts

@@ -25,6 +25,10 @@ export const workspacePermissions = {
       description: "Delete apis in this workspace.",
       permission: "api.*.delete_api",
     },
+    read_analytics: {
+      description: "Query analytics data for all API's in this workspace using SQL.",
+      permission: "api.*.read_analytics",
+    },
   },
   Keys: {
     verify_key: {
@@ -170,6 +174,10 @@ export function apiPermissions(apiId: string): {
         description: "Update this API.",
         permission: `api.${apiId}.update_api`,
       },
+      read_analytics: {
+        description: "Query analytics data for this API using SQL.",
+        permission: `api.${apiId}.read_analytics`,
+      },
     },
     Keys: {
       verify_key: {

apps/docs/analytics/getting-started.mdx

@@ -0,0 +1,171 @@
+---
+title: Getting Started
+description: "Request access and run your first analytics query"
+---
+
+## Request Access
+
+<Warning>
+  **Analytics is currently in private beta and available by request only.**
+</Warning>
+
+To get started:
+
+1. **Find your workspace ID** in the Unkey dashboard settings
+2. **Email us** at [support@unkey.dev](mailto:support@unkey.dev) with:
+   - Your workspace ID
+   - Your use case (billing, dashboards, reporting, etc.)
+   - Expected query volume
+
+We'll enable analytics for your workspace and send you confirmation.
+
+## Authentication
+
+Analytics queries require a root key with analytics permissions. Create one in your dashboard:
+
+1. Go to **Settings** → **Root Keys**
+2. Click **Create New Root Key**
+3. Select permissions: `api.*.read_analytics` OR `api.<api_id>.read_analytics`
+4. Copy and securely store your root key
+
+<Warning>
+  Root keys have powerful permissions. Store them securely and never commit them
+  to version control.
+</Warning>
+
+## Your First Query
+
+Once you have access, execute your first analytics query using the `/v2/analytics.getVerifications` endpoint.
+
+### Count Total Verifications
+
+```sql
+SELECT COUNT(*) as total
+FROM key_verifications_v1
+WHERE time >= now() - INTERVAL 7 DAY
+```
+
+Execute this query with curl:
+
+```bash
+curl -X POST https://api.unkey.com/v2/analytics.getVerifications \
+  -H "Authorization: Bearer <YOUR_ROOT_KEY>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "SELECT COUNT(*) as total FROM key_verifications_v1 WHERE time >= now() - INTERVAL 7 DAY"
+  }'
+```
+
+### Break Down by Outcome
+
+```sql
+SELECT
+  outcome,
+  COUNT(*) as count
+FROM key_verifications_v1
+WHERE time >= now() - INTERVAL 24 HOUR
+GROUP BY outcome
+ORDER BY count DESC
+```
+
+Execute this query with curl:
+
+```bash
+curl -X POST https://api.unkey.com/v2/analytics.getVerifications \
+  -H "Authorization: Bearer <YOUR_ROOT_KEY>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "SELECT outcome, COUNT(*) as count FROM key_verifications_v1 WHERE time >= now() - INTERVAL 24 HOUR GROUP BY outcome ORDER BY count DESC"
+  }'
+```
+
+### Top Users by Usage
+
+```sql
+SELECT
+  external_id,
+  SUM(count) as verifications
+FROM key_verifications_per_day_v1
+WHERE time >= now() - INTERVAL 30 DAY
+GROUP BY external_id
+ORDER BY verifications DESC
+LIMIT 10
+```
+
+Execute this query with curl:
+
+```bash
+curl -X POST https://api.unkey.com/v2/analytics.getVerifications \
+  -H "Authorization: Bearer <YOUR_ROOT_KEY>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "SELECT external_id, SUM(count) as verifications FROM key_verifications_per_day_v1 WHERE time >= now() - INTERVAL 30 DAY GROUP BY external_id ORDER BY verifications DESC LIMIT 10"
+  }'
+```
+
+<Tip>
+  **Performance tip:** For longer time ranges, use pre-aggregated tables instead of the raw table:
+  - `key_verifications_per_minute_v1` - For queries spanning hours
+  - `key_verifications_per_hour_v1` - For queries spanning days
+  - `key_verifications_per_day_v1` - For queries spanning weeks/months
+  - `key_verifications_per_month_v1` - For queries spanning years
+
+Use `SUM(count)` instead of `COUNT(*)` with aggregated tables. They scan far fewer rows and are much faster.
+
+</Tip>
+
+<Tip>
+  Check out the [Query Examples](/analytics/query-examples) page for 30+
+  ready-to-use queries covering billing, monitoring, and analytics use cases.
+</Tip>
+
+## Understanding the Response
+
+Analytics queries return data as an array of objects:
+
+```json
+{
+  "meta": {
+    "requestId": "req_xxx"
+  },
+  "data": [
+    { "outcome": "VALID", "count": 1234 },
+    { "outcome": "RATE_LIMITED", "count": 56 },
+    { "outcome": "USAGE_EXCEEDED", "count": 12 }
+  ]
+}
+```
+
+Each object in the `data` array contains fields from your SELECT clause. The field names match the column names or aliases you specified in your query.
+
+## Filtering by API or User
+
+You can filter queries to specific APIs or users. Use `key_space_id` to filter by API (find this identifier in your API settings) and `external_id` to filter by user. These fields support standard SQL operators: `=`, `!=`, `IN`, `NOT IN`, `<`, `>`, etc.
+
+<Note>
+  Queries are subject to resource limits (execution time, memory, result size,
+  and quota). See [Query Restrictions](/analytics/query-restrictions) for
+  complete details on limits and error codes.
+</Note>
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Query Examples" icon="code" href="/analytics/query-examples">
+    Explore common SQL patterns for analytics and billing
+  </Card>
+  <Card
+    title="Schema Reference"
+    icon="table"
+    href="/analytics/schema-reference"
+  >
+    Browse available tables, columns, and data types
+  </Card>
+  <Card
+    title="Query Restrictions"
+    icon="shield-check"
+    href="/analytics/query-restrictions"
+  >
+    View limits, quotas, and permissions
+  </Card>
+</CardGroup>