Workspace Metrics API

Overview

The Workspace Metrics API provides on-demand usage analytics for workspace owners. It supports multiple metric types with flexible filtering, grouping, and aggregation capabilities to power dashboard visualizations.

Authentication

This endpoint requires authentication via the standard API authentication middleware. Only workspace owners can access metrics for their workspace.

Quick Start

Get a Simple Count (Stat Card)

To get the total count of agents created in the last 30 days:

{
  "workspace_uuid": "your-workspace-uuid",
  "entity": "agents",
  "metric": "created",
  "aggregation": "count"
}

Get a Leaderboard (Top Users)

To get the top 10 users by workflow executions:

{
  "workspace_uuid": "your-workspace-uuid",
  "entity": "workflows",
  "metric": "executions",
  "aggregation": "count",
  "group_by": "user",
  "order_by": "value",
  "order_dir": "desc",
  "limit": 10
}

Get Time Series Data (Line Chart)

To get daily agent executions for the last 30 days:

{
  "workspace_uuid": "your-workspace-uuid",
  "entity": "agents",
  "metric": "executions",
  "aggregation": "count",
  "group_by": "date",
  "granularity": "daily",
  "filters": {
    "period": "30d"
  }
}

Supported Entities

Entity	Description
`agents`	AI Agents created in the workspace
`workflows`	Automation workflows

Supported Metrics

Metric	Agents	Workflows	Description
`executions`	✅	✅	Number of times the entity was run
`created`	✅	✅	Number of entities created
`copies`	✅	✅	Number of entities cloned from templates
`shares`	✅	✅	Number of entities shared with others
`avg_duration`	❌	✅	Average execution time (milliseconds)

Note: The avg_duration metric is only available for workflows and does not support grouping.

Grouping Options

No Grouping (Total Only)

When group_by is not provided, the API returns only the total value:

{
  "workspace_uuid": "your-workspace-uuid",
  "entity": "agents",
  "metric": "created",
  "aggregation": "count"
}

Response:

{
  "data": {
    "entity": "agents",
    "metric": "created",
    "aggregation": "count",
    "group_by": null,
    "granularity": null,
    "total": 47,
    "results": []
  }
}

Group by User

Returns a breakdown by user, perfect for leaderboards:

{
  "workspace_uuid": "your-workspace-uuid",
  "entity": "workflows",
  "metric": "executions",
  "aggregation": "count",
  "group_by": "user",
  "limit": 5
}

Response:

{
  "data": {
    "entity": "workflows",
    "metric": "executions",
    "aggregation": "count",
    "group_by": "user",
    "total": 890,
    "results": [
      { "user_id": "user-uuid-1", "user_name": "John Doe", "value": 150 },
      { "user_id": "user-uuid-2", "user_name": "Jane Smith", "value": 120 }
    ]
  }
}

Group by Date

Returns time series data. Requires the granularity parameter:

{
  "workspace_uuid": "your-workspace-uuid",
  "entity": "agents",
  "metric": "executions",
  "aggregation": "count",
  "group_by": "date",
  "granularity": "daily"
}

Response:

{
  "data": {
    "entity": "agents",
    "metric": "executions",
    "aggregation": "count",
    "group_by": "date",
    "granularity": "daily",
    "total": 1250,
    "results": [
      { "date": "2026-01-01", "value": 45 },
      { "date": "2026-01-02", "value": 52 }
    ]
  }
}

Granularity Options

Value	Format	Example
`daily`	`YYYY-MM-DD`	`2026-01-15`
`weekly`	`YYYY-WW`	`2026-03` (year-week)
`monthly`	`YYYY-MM`	`2026-01`

Filtering

Filter by Period

Use filters.period to specify the time range:

Value	Description
`7d`	Last 7 days
`30d`	Last 30 days (default)
`90d`	Last 90 days
`all`	All time

{
  "workspace_uuid": "your-workspace-uuid",
  "entity": "agents",
  "metric": "executions",
  "aggregation": "count",
  "filters": {
    "period": "7d"
  }
}

Filter by User

To get metrics for a specific user, use filters.user_id:

{
  "workspace_uuid": "your-workspace-uuid",
  "entity": "agents",
  "metric": "executions",
  "aggregation": "count",
  "group_by": "date",
  "granularity": "daily",
  "filters": {
    "period": "30d",
    "user_id": 123
  }
}

Sorting and Limiting

Order By

Value	Description
`value`	Sort by metric value (default)
`name`	Sort by user name
`date`	Sort by date

Order Direction

Value	Description
`desc`	Descending order (default)
`asc`	Ascending order

Limit

Control the number of results returned (1-100, default: 10):

{
  "workspace_uuid": "your-workspace-uuid",
  "entity": "workflows",
  "metric": "executions",
  "aggregation": "count",
  "group_by": "user",
  "order_by": "value",
  "order_dir": "desc",
  "limit": 5
}

Use Case Examples

Dashboard Stat Cards

Get individual totals for each stat card:

Total Agents Created:

{
  "workspace_uuid": "uuid",
  "entity": "agents",
  "metric": "created",
  "aggregation": "count",
  "filters": { "period": "30d" }
}

Total Workflow Executions:

{
  "workspace_uuid": "uuid",
  "entity": "workflows",
  "metric": "executions",
  "aggregation": "count",
  "filters": { "period": "30d" }
}

Average Workflow Duration:

{
  "workspace_uuid": "uuid",
  "entity": "workflows",
  "metric": "avg_duration",
  "aggregation": "avg",
  "filters": { "period": "30d" }
}

User Activity Chart

Weekly agent executions per user for the last 90 days:

{
  "workspace_uuid": "uuid",
  "entity": "agents",
  "metric": "executions",
  "aggregation": "count",
  "group_by": "date",
  "granularity": "weekly",
  "filters": { "period": "90d" }
}

Employee Drilldown

Get a specific user's daily workflow executions:

{
  "workspace_uuid": "uuid",
  "entity": "workflows",
  "metric": "executions",
  "aggregation": "count",
  "group_by": "date",
  "granularity": "daily",
  "filters": {
    "period": "30d",
    "user_id": 123
  }
}

Adoption Metrics

Agents shared in the last 30 days by user:

{
  "workspace_uuid": "uuid",
  "entity": "agents",
  "metric": "shares",
  "aggregation": "count",
  "group_by": "user",
  "filters": { "period": "30d" },
  "limit": 10
}

Response Structure

All successful responses follow this structure:

{
  "data": {
    "entity": "string",
    "metric": "string",
    "aggregation": "string",
    "group_by": "string|null",
    "granularity": "string|null",
    "total": "number",
    "results": []
  },
  "meta": {
    "period": {
      "from": "YYYY-MM-DD",
      "to": "YYYY-MM-DD"
    },
    "cached_at": "ISO 8601 timestamp",
    "cache_ttl": 300,
    "unit": "string|null"
  }
}

Response Fields

data.total - The aggregate value across all results

data.results - Array of grouped results (empty when no group_by)

meta.period - The actual date range used for the query

meta.cached_at - When this response was cached

meta.cache_ttl - Cache time-to-live in seconds (5 minutes)

meta.unit - Unit of measurement (e.g., "milliseconds" for avg_duration)

Caching

Responses are cached for 5 minutes (300 seconds). The meta.cached_at field indicates when the cached response was generated. Identical requests within the cache window return the same cached data.

Error Handling

Validation Errors (422)

Invalid requests return validation errors:

{
  "message": "The entity field is required.",
  "errors": {
    "entity": ["The entity field is required."]
  }
}

Common Validation Rules

entity is required and must be agents or workflows

metric is required and must be a supported metric for the entity

aggregation is required and must be count, sum, or avg

granularity is required when group_by is date

avg_duration metric does not support group_by

avg_duration metric is only available for workflows

Authorization Errors (403)

Non-owners attempting to access metrics will receive:

{
  "message": "This action is unauthorized."
}

Not Found (404)

Invalid workspace UUID:

{
  "error": "Workspace not found"
}

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Get Workspaces Metrics

Workspace Metrics API

Overview

Authentication

Quick Start

Get a Simple Count (Stat Card)

Get a Leaderboard (Top Users)

Get Time Series Data (Line Chart)

Supported Entities

Supported Metrics

Grouping Options

No Grouping (Total Only)

Group by User

Group by Date

Granularity Options

Filtering

Filter by Period

Filter by User

Sorting and Limiting

Order By

Order Direction

Limit

Use Case Examples

Dashboard Stat Cards

User Activity Chart

Employee Drilldown

Adoption Metrics

Response Structure

Response Fields

Caching

Error Handling

Validation Errors (422)

Common Validation Rules

Authorization Errors (403)

Not Found (404)

Request

Responses

Get Workspaces Metrics

Workspace Metrics API#

Overview#

Authentication#

Quick Start#

Get a Simple Count (Stat Card)#

Get a Leaderboard (Top Users)#

Get Time Series Data (Line Chart)#

Supported Entities#

Supported Metrics#

Grouping Options#

No Grouping (Total Only)#

Group by User#

Group by Date#

Granularity Options#

Filtering#

Filter by Period#

Filter by User#

Sorting and Limiting#

Order By#

Order Direction#

Limit#

Use Case Examples#

Dashboard Stat Cards#

User Activity Chart#

Employee Drilldown#

Adoption Metrics#

Response Structure#

Response Fields#

Caching#

Error Handling#

Validation Errors (422)#

Common Validation Rules#

Authorization Errors (403)#

Not Found (404)#

Request

Responses

Workspace Metrics API

Overview

Authentication

Quick Start

Get a Simple Count (Stat Card)

Get a Leaderboard (Top Users)

Get Time Series Data (Line Chart)

Supported Entities

Supported Metrics

Grouping Options

No Grouping (Total Only)

Group by User

Group by Date

Granularity Options

Filtering

Filter by Period

Filter by User

Sorting and Limiting

Order By

Order Direction

Limit

Use Case Examples

Dashboard Stat Cards

User Activity Chart

Employee Drilldown

Adoption Metrics

Response Structure

Response Fields

Caching

Error Handling

Validation Errors (422)

Common Validation Rules

Authorization Errors (403)

Not Found (404)