Mastra 平台推出 Metrics API：按智能体、线程或时间查询成本、延迟与错误

Query cost, latency, and errors by agent, thread, or time.

Oct 13, 2026

4 min read

You can now query token usage, model cost, latency, and error rates with Mastra platform's Metrics API. Use the Mastra Client SDK, Mastra CLI, or observability endpoints to get totals, breakdowns, time series, and percentile data from production Mastra projects.

Traces show what happened in a single run, while metrics aggregate across every run. This lets you see which model, conversation, or tool calls cost the most, run the slowest, or fail most often. You can combine query types with time ranges and status filters to surface important insights to share with your team.

We launched metrics earlier this year, letting you view model costs, latency, and error counts in Mastra platform and Studio. Today, using the Metrics API, you can construct your own queries to generate custom reports, build dashboards, send data to downstream services, or post alerts to connected chat platforms when model costs or error rates rise.

You can combine the Metrics API with code mode to build agents capable of constructing their own queries on the fly to answer questions, summarize insights, or generate PDFs for team members and stakeholders.

Metric queries need a platform access token and your project ID, sent with each request. Use the correct Mastra observability base URL for your project's region:

Each example below asks for total token usage and estimated cost for the last 30 days. The timestamp filter is optional. If start and end are omitted, queries return all available data.

Mastra Client SDK

Use the analytics methods with Mastra Client SDK:

Mastra CLI

Install or upgrade the Mastra CLI globally:

Run the mastra api metric commands from your terminal. The CLI reads MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID from your environment:

Observability endpoints

Send a POST request to one of the Metrics API endpoints. Include the MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID variables in the request:

Example Response

All requests are returned as JSON:

Example queries

The following examples show how to query cost by token type, the most expensive conversations, daily token usage, latency percentiles, and failed runs. Each example uses the Mastra Client SDK, but the same queries work with the Mastra CLI and observability endpoints.

Cost by token type

Query each token type on its own to see what drives cost. Cache writes, cache reads, and output tokens are priced differently:

Cost by conversation

Group token usage by threadId to rank conversations by cost:

The same call with groupBy: ["model"] gives cost by model, and groupBy: ["rootEntityName"] gives cost by the agent or workflow.

Get p50 and p95 agent run durations for each day:

Failed runs

Filter duration metrics by their status label to count failed runs:

For more information and full configuration options, see:

Metrics API on Mastra platform; Metric queries reference; Automatic metrics; Metrics overview; Observability on Mastra platform; mastra api metric CLI reference; Mastra platform regions; Code mode

Paul Scanlon sits between Developer Education and Product Marketing at Mastra. Previously, he was a Technical Product Marketing Manager at Neon and worked in Developer Relations at Gatsby, where he created educational content and developer experiences.

On this page