Mastra Platform Adds Metrics API for Token Usage, Cost and Latency

What the Metrics API does

According to Mastra, traces show what happened in a single run, while metrics aggregate across every run. That makes it possible to see which model, conversation or tool calls cost the most, run the slowest or fail most often. Queries can be combined with time ranges and status filters, so teams can pull out insights to share.

Mastra says it launched metrics earlier this year, with model costs, latency and error counts visible in Mastra platform and Studio. With the Metrics API, users can now build their 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.

The company also points to a combination with code mode. According to Mastra, this can be used to build agents that construct their own queries on the fly to answer questions, summarize insights or generate PDFs for team members and stakeholders.

How to get started

Each metric query needs a platform access token and a project ID, sent with every request. Mastra provides two regional observability base URLs: US at https://observability.mastra.ai and EU at https://observability.eu.mastra.ai. The timestamp filter is optional. If start and end are omitted, queries return all available data.

• Mastra Client SDK: install @mastra/client-js@latest. It requires version 1.9.0 or later, added in PR #14270.
• Mastra CLI: install mastra@latest globally. It requires version 1.9.2 or later, added in PR #16563. The mastra api metric commands read MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID from the environment.
• Observability endpoints: send a POST request to one of the Metrics API endpoints, including the access token and project ID in the request headers.

Mastra's examples ask for total token usage and estimated cost over 30 days, with a comparison to the previous period. All responses come back as JSON. In the sample response, the value is 6332830 tokens with an estimated cost of 14.66 USD, against a previous value of 866647, a change of 630.7 percent. The previous estimated cost and cost change are null in that example.

Example queries

Mastra shows several query types, all written with the Client SDK but, according to the company, equally usable from the CLI and the endpoints.

• Cost by token type: query each token type separately, since cache writes, cache reads and output tokens are priced differently.
• Cost by conversation: group token usage by threadId to rank conversations by cost. Grouping by model gives cost by model, and grouping by rootEntityName gives cost by agent or workflow.
• Tokens per day: a time series with a 1d interval returns daily usage.
• Latency percentiles: request p50 and p95 agent run durations per day using the mastra_agent_duration_ms metric.
• Failed runs: count duration metrics filtered by the status label set to error.

What it means for teams

For teams running agents in production, the API turns metrics already visible in the platform into data they can query and route elsewhere. Cost tracking by model, conversation, agent or workflow, together with latency percentiles and error counts, can feed internal dashboards, reports and chat alerts. Mastra's documentation covers the full configuration options, including a metric queries reference and a CLI reference.