Metrics

The Metrics API provides a unified interface for retrieving aggregated statistics across multiple resources in your workspace. Whether you need to count agents, track message volume over time, or analyze numeric properties of your data, the Metrics API uses a consistent request and response structure that makes it easy to build dashboards and analytics features.

All metrics endpoints share the same underlying architecture. Once you understand how to query metrics for one resource, the same concepts apply to all others. The only differences between endpoints are the resource-specific filters available for each type.

Available Endpoints

The following resources expose metrics endpoints:

Resource	Endpoint	Description
Agents	`POST /v1/agents/metrics`	Statistics about AI agents
Workflows	`POST /v1/workflows/metrics`	Statistics about automation workflows
Workflow Executions	`POST /v1/workflow-executions/metrics`	Statistics about workflow runs
Threads	`POST /v1/threads/metrics`	Statistics about conversation threads
Messages	`POST /v1/messages/metrics`	Statistics about individual messages

All endpoints require authentication and workspace context.

Calculation Types

The calculation parameter determines what kind of aggregation to perform on your data. There are four calculation types, organized into two categories: accumulated calculations return a single value, while time series calculations return data points grouped by time period.

Accumulated Count

The accumulated_count calculation returns the total number of resources matching your filters. This is the simplest calculation type and requires no additional parameters.

Use accumulated count when you need a single number, such as displaying a total count in a dashboard widget or comparing counts between different filter combinations.

calculation: accumulated_count

The response includes a total field with the count, and a data array containing a single object with the value.

Time Series Count

The time_series_count calculation breaks down counts by time period, allowing you to visualize trends and patterns. This calculation requires the granularity parameter to specify how data should be grouped.

Use time series count when building charts that show resource creation over time, such as a line graph of new agents per week.

calculation: time_series_count
granularity: daily

The response data array contains objects with date and value fields, sorted chronologically. The total field contains the sum of all values.

Accumulated Average

The accumulated_average calculation computes the mean value of a specific numeric column across all matching resources. This calculation requires the column parameter specifying which field to average.

Use accumulated average when you need aggregate statistics on numeric fields.

calculation: accumulated_average
column: <numeric_column>

The response includes the average in the total field. The data array contains an object with the value and count (the number of records used in the calculation).

Note: The column parameter cannot be * for average calculations. You must specify a valid numeric column name from the resource's database schema.

Time Series Average

The time_series_average calculation computes averages grouped by time period. This requires both the column and granularity parameters.

Use time series average to track how numeric metrics change over time.

calculation: time_series_average
column: <numeric_column>
granularity: weekly

The response data array contains objects with date, value (the average for that period), and count (number of records in that period).

Granularity

When using time series calculations, the granularity parameter controls how data points are grouped:

Value	Grouping
`daily`	Each data point represents a single calendar day
`weekly`	Each data point represents a week, starting on Monday
`monthly`	Each data point represents a calendar month

Choose granularity based on your date range and visualization needs. For short ranges (7-14 days), daily provides the most detail. For longer ranges (several months to a year), weekly or monthly prevents charts from becoming cluttered with too many data points.

Note: Granularity is required for time series calculations. For accumulated calculations, this parameter is ignored if provided.

Date Filtering

The date_from and date_to parameters filter resources by their creation timestamp. Both parameters accept dates in YYYY-MM-DD format.

date_from: 2025-01-01
date_to: 2025-01-31

Date filtering behavior:

Both omitted: All resources are included regardless of creation date

Only date_from: Resources created on or after the specified date

Only date_to: Resources created on or before the specified date

Both specified: Resources created within the inclusive date range

The date range is inclusive on both ends. When date_from is 2025-01-01, resources created at any time on January 1st are included. When date_to is 2025-01-31, resources created up to 23:59:59 on January 31st are included.

Resource-Specific Filters

Beyond the common metrics parameters, each endpoint accepts filters specific to that resource type. These filters narrow down which resources are included in the calculation. Each endpoint only accepts the filters listed below—passing an unrecognized filter will result in a validation error.

Agent filters:

workspace_uuid - Scope to a specific workspace

user_id - Agents created by a specific user

search - Text search across agent name and description

visibility - Filter by public, private, or workspace

category_uuids - Agents in specific categories

favorite - Only favorited agents

template - Only template agents

Workflow filters:

workspace_uuid - Scope to a specific workspace

user_id - Workflows created by a specific user

search - Text search across workflow name and description

visibility - Filter by public, private, or workspace

category_uuids - Workflows in specific categories

favorite - Only favorited workflows

template - Only template workflows

Thread filters:

workspace_uuid - Scope to a specific workspace

user_id - Threads created by a specific user

search - Text search across thread content

agent_uuid - Threads for a specific agent

Message filters:

search - Text search across message content

thread_uuid - Messages in a specific thread

Workflow Execution filters:

user_id - Executions triggered by a specific user

workflow_uuid - Executions of a specific workflow

workflow_uuids - Executions of multiple specific workflows (array)

Filters are applied before calculations, ensuring your metrics reflect exactly the subset of resources you're interested in.

Caching

Metrics results are cached for 5 minutes to optimize performance for repeated queries. This caching behavior has several implications:

Cache keys are generated from all query parameters. Changing any parameter—even adding a filter—produces a different cache key and bypasses the existing cache.

The cached_at field in the response indicates when the data was computed. Use this to determine data freshness in your application.

For real-time dashboards, consider that displayed data may be up to 5 minutes old. If stricter freshness is required, you may need to communicate this latency to users or implement client-side cache invalidation strategies.

{
    "cached_at": "2025-01-15T10:30:00.000000Z"
}

Practical Examples

To display total counts in a dashboard overview, use accumulated count calculations for each resource type:

Total agents in workspace:

POST /v1/agents/metrics

{
    "calculation": "accumulated_count"
}

Active workflows this month:

POST /v1/workflows/metrics

{
    "calculation": "accumulated_count",
    "date_from": "2025-01-01",
    "date_to": "2025-01-31"
}

Visualizing Growth Trends

To build a line chart showing resource growth, use time series count with appropriate granularity:

Daily message volume for the past week:

POST /v1/messages/metrics

{
    "calculation": "time_series_count",
    "granularity": "daily",
    "date_from": "2025-01-08",
    "date_to": "2025-01-15"
}

Monthly workflow executions for the past year:

POST /v1/workflow-executions/metrics

{
    "calculation": "time_series_count",
    "granularity": "monthly",
    "date_from": "2024-01-01",
    "date_to": "2024-12-31"
}

Comparing Metrics Across Resources

To build a comprehensive analytics view, query multiple endpoints with consistent date ranges:

// All requests use the same date range for accurate comparison
date_from: 2025-01-01
date_to: 2025-01-31

POST /v1/agents/metrics      → Total agents created
POST /v1/threads/metrics     → Total conversations started
POST /v1/messages/metrics    → Total messages exchanged
POST /v1/workflows/metrics   → Total workflows created
POST /v1/workflow-executions/metrics → Total automations run

By using identical date ranges across all requests, you can correlate metrics and identify patterns, such as whether increased agent creation leads to proportionally higher message volume.

Available Endpoints#

Calculation Types#

Accumulated Count#

Time Series Count#

Accumulated Average#

Time Series Average#

Granularity#

Date Filtering#

Resource-Specific Filters#

Caching#

Practical Examples#

Building a Dashboard Widget#

Visualizing Growth Trends#

Comparing Metrics Across Resources#

Available Endpoints

Calculation Types

Accumulated Count

Time Series Count

Accumulated Average

Time Series Average

Granularity

Date Filtering

Resource-Specific Filters

Caching

Practical Examples

Building a Dashboard Widget

Visualizing Growth Trends

Comparing Metrics Across Resources