Usage Stats & Analytics

Endpoints for viewing app usage statistics, workspace storage, and server route invocation history.

GET /api/apps/{id}/stats

Get aggregated usage statistics for an app including view counts, API invocations, and workspace storage.

Authentication: Required

Path Parameters:

Parameter	Type	Description
`id`	string	App UUID or natural ID

Response:

{
  "appId": "d4f8a2b1-1234-5678-90ab-cdef12345678",
  "totalViews": 142,
  "uniqueViewers": 23,
  "views7d": 45,
  "views30d": 89,
  "lastViewedAt": "2024-02-23T14:30:00.000Z",
  "viewsByDay": [
    { "day": "2024-02-23", "count": 12 },
    { "day": "2024-02-22", "count": 8 },
    { "day": "2024-02-21", "count": 5 }
  ],
  "api": {
    "totalInvocations": 1200,
    "invocations7d": 340,
    "invocations30d": 780,
    "avgDurationMs": 245,
    "errorCount30d": 12,
    "errorRate30d": 1.54,
    "peakMemoryBytes": 52428800,
    "totalComputeMs": 190740
  },
  "storage": {
    "hasWorkspace": true,
    "schemaSize": 2097152,
    "tableCount": 3,
    "quotaBytes": 1073741824,
    "quotaPercent": 0.2
  }
}

Key Fields:

Field	Description
`totalViews`	All-time view count
`uniqueViewers`	Distinct users who viewed the app
`views7d` / `views30d`	View counts over the last 7 and 30 days
`viewsByDay`	Daily breakdown for the last 7 days
`api.totalInvocations`	Total server route invocations
`api.errorRate30d`	Error percentage over last 30 days
`storage.hasWorkspace`	Whether the app has a Postgres workspace
`storage.schemaSize`	Workspace disk usage in bytes
`storage.quotaPercent`	Percentage of storage quota used

Permissions Required: None (404 if user cannot read this app)

GET /api/apps/{id}/stats/tables

List all tables in the app's Postgres workspace with column metadata.

Authentication: Required

Permissions Required: Member+ role (write permission)

Path Parameters:

Parameter	Type	Description
`id`	string	App UUID or natural ID

Response:

Returns an empty array if the app has no workspace schema.

[
  {
    "name": "users",
    "rowCount": 1250,
    "sizeBytes": 524288,
    "columns": [
      {
        "name": "id",
        "type": "uuid",
        "nullable": false,
        "primaryKey": true
      },
      {
        "name": "email",
        "type": "character varying",
        "nullable": false,
        "indexed": true
      },
      {
        "name": "created_at",
        "type": "timestamp with time zone",
        "nullable": true
      }
    ]
  }
]

Key Fields:

Field	Description
`rowCount`	Approximate row count from `pg_stat_user_tables`
`sizeBytes`	Total relation size from `pg_total_relation_size()`
`columns[].primaryKey`	Whether the column is part of the primary key
`columns[].indexed`	Whether the column has an index

Internal Tables

The _migrations table used for tracking applied migrations is excluded from the response.

POST /api/apps/{id}/stats/tables/{table}/preview

Preview rows from a table in the app's workspace.

Authentication: Required

Permissions Required: Member+ role (write permission)

Path Parameters:

Parameter	Type	Description
`id`	string	App UUID or natural ID
`table`	string	Table name

Payload:

{
  "limit": 25,
  "offset": 0
}

Field	Type	Default	Description
`limit`	integer	25	Rows per page (1-100)
`offset`	integer	0	Row offset for pagination

Response:

{
  "rows": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "user@example.com",
      "created_at": "2024-02-01T10:00:00Z"
    }
  ],
  "rowCount": 1,
  "totalRows": 1250,
  "fields": [
    { "name": "id", "dataTypeID": 2950 },
    { "name": "email", "dataTypeID": 1043 },
    { "name": "created_at", "dataTypeID": 1184 }
  ]
}

Key Fields:

Field	Description
`rowCount`	Number of rows returned in this page
`totalRows`	Total rows in the table
`fields`	Column metadata with Postgres data type OIDs

Table Validation

The table name is validated against information_schema to prevent SQL injection. Requests for non-existent tables or the _migrations table return 404 Not Found.

GET /api/apps/{id}/stats/api

Get detailed server route invocation history and daily aggregates.

Authentication: Required

Permissions Required: Member+ role (write permission)

Path Parameters:

Parameter	Type	Description
`id`	string	App UUID or natural ID

Response:

{
  "recent": [
    {
      "method": "GET",
      "path": "/api/datasets/123/search",
      "username": "john.doe",
      "startedAt": "2024-02-23T14:30:00.000Z",
      "durationMs": 245,
      "statusCode": 200,
      "memoryPeakBytes": 52428800,
      "error": null
    }
  ],
  "daily": [
    {
      "day": "2024-02-23",
      "count": 45,
      "avgDurationMs": 234,
      "errorCount": 1
    }
  ]
}

Key Fields:

Field	Description
`recent`	Last 100 invocations, ordered by `startedAt` descending
`recent[].memoryPeakBytes`	Peak memory usage of the V8 isolate
`recent[].error`	Error message if the invocation failed, `null` otherwise
`daily`	Daily aggregates for the last 30 days
`daily[].avgDurationMs`	Average handler execution time for the day

GET /api/apps/{id}/usage

Get this app's AI credit consumption — current-month totals, a trailing monthly trend, a daily breakdown, per-model AI spend, and the top users driving the app. Powers the Usage tab of the App Admin Panel.

Every figure is scoped to this app via the (entityId, entityType = 'app') attribution stamped on usage_event / audit.ai_log rows at capture time, so only usage actually attributed to this app appears.

Authentication: Required

Permissions Required: app:write (403 if the user can read the app but lacks write; 404 if the user cannot read this app at all)

Path Parameters:

Parameter	Type	Description
`id`	string	App UUID or natural ID

Query Parameters:

Parameter	Type	Default	Description
`months`	integer	12	Trailing months for the trend (`history`), 1-24
`days`	integer	30	Rolling window for `topUsers`, 1-90

Response:

All totalCredits / totalEvents are numbers. Collections are always arrays (empty when the app has no usage).

{
  "months": 12,
  "windowDays": 30,
  "summary": [
    { "entityId": "d4f8a2b1-…", "entityType": "app", "resourceType": "app_compute", "totalCredits": 98.49, "totalEvents": 591 },
    { "entityId": "d4f8a2b1-…", "entityType": "app", "resourceType": "ai", "totalCredits": 50, "totalEvents": 8 }
  ],
  "dailyTotals": [
    { "date": "2024-02-23", "resourceType": "ai", "totalCredits": 12.5 }
  ],
  "history": [
    { "month": "2024-02", "resourceType": "ai", "totalCredits": 50, "totalEvents": 8 }
  ],
  "byModel": [
    { "model": "gpt-4o", "totalCredits": 30, "totalEvents": 4 },
    { "model": "gpt-4o-mini", "totalCredits": 2, "totalEvents": 1 }
  ],
  "topUsers": [
    { "actor": "jdoe", "actorType": "user", "displayName": "Jane Doe", "totalCredits": 40, "totalEvents": 12 }
  ]
}

Key Fields:

Field	Description
`summary`	Current-month credits per resource type (`ai`, `agent_run`, `app_compute`, …); each row also carries this app's `entityId` / `entityType`
`dailyTotals`	Current-month credits per day and resource type
`history`	Trailing `months` of monthly credits by resource type — the trend chart
`byModel`	Current-month AI credits grouped by model (from `audit.ai_log`), biggest first
`topUsers`	Top actors over the trailing `days`; `displayName` falls back to the actor id for agents/system actors

AI attribution

byModel and the ai resource type only reflect AI calls tagged with this app's id at capture time (agent runs, app compute, and app-context AI). Usage that isn't app-attributed appears on the tenant-wide Settings → Usage page instead.

GET /api/apps/{id}/stats​

GET /api/apps/{id}/stats/tables​

POST /api/apps/{id}/stats/tables/{table}/preview​

GET /api/apps/{id}/stats/api​

GET /api/apps/{id}/usage​

GET /api/apps/{id}/stats

GET /api/apps/{id}/stats/tables

POST /api/apps/{id}/stats/tables/{table}/preview

GET /api/apps/{id}/stats/api

GET /api/apps/{id}/usage