Mastra adds span queries to filter and group spans across all traces

From whole traces to individual spans

Until now, trace queries could filter on details deep within a trace, such as a failed tool call, but they returned the whole trace. According to Mastra, that meant finding failed tool calls required opening and inspecting each trace one by one. Span queries are more granular: they search within every trace and return just the spans that match.

In the Mastra platform and Studio, the Spans tab lets users filter by time range, span type, span name, status, error, duration, and more. Mastra says a coding agent can build the same queries through the CLI, the Client SDK and the HTTP endpoints in order to find and fix issues.

Grouping and aggregating spans

Span queries can also group or aggregate across matching spans, with measures such as counts, error rates and latency. Mastra suggests using them to spot which tool is failing or running slowly, or to track tool latency over time, and then to run span queries with the same filters to inspect the problematic calls.

The documented limits are:

• Each query can combine up to 100 conditions, using fields like spanType, entityName, status, durationMs and parentEntityName.
• Span queries return up to 1,000 spans per page.
• Span groups can group by up to 2 dimensions over a timeRange of up to 365 days.

The feature works on the Mastra platform and on self-hosted Mastra projects where storage.observability uses DuckDB, PostgreSQL, or ClickHouse. Teams whose trace data lives outside Mastra can bring their existing history over with trace imports.

Four ways to run a query

Span queries need a platform access token and a project ID, sent with each request. The base URL depends on the project's region: https://observability.mastra.ai for the US and https://observability.eu.mastra.ai for the EU.

Mastra's examples group tool calls from the last 7 days by tool, then find the tool calls that ended in an error.

• Mastra CLI: requires [email protected] or later. The mastra api span aggregate command returns call count, error rate and p95 latency for every tool, and mastra api span query finds tool calls that ended in an error. The CLI reads MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID from the environment.
• Mastra platform and Studio: the Spans tab provides the filters.
• Mastra Client SDK: requires @mastra/[email protected] or later. aggregateSpans() returns call count, error rate and p95 latency per tool, with the worst offenders first, and adding an interval such as 1d tracks latency over time using p50, p95 and p99. querySpans() returns the failing tool calls.
• Observability endpoints: a POST request can be sent to the span group and span query endpoints, with the token and project ID in the headers.

What it means for teams building agents

For teams running agents on Mastra, the change shifts debugging from inspecting traces one at a time to querying the spans directly. An aggregate view can show which tool has the highest error rate or latency, and a follow-up query with the same filters returns the specific failing calls. Because the same queries are exposed through the CLI, SDK and HTTP endpoints, coding agents can run them as well as people using the Studio interface.

Mastra points to its Client SDK observability reference, the aggregate spans reference, the mastra api span query CLI reference and its platform observability documentation for full configuration options.