Mastra adds trace queries to find failed tool calls and slow model runs

What trace queries do

According to Mastra, the platform and the local Studio now let users filter traces by fields such as time, primitive name, agent or workflow ID, status, score and feedback. The same queries can be built through the CLI, the Mastra Client SDK and HTTP observability endpoints, which means a coding agent can run them as well.

Mastra points to one use case in particular: letting a coding agent look for traces that errored out or failed, or for slow model calls, and then fix them.

Queries on top-level trace fields cover when a trace ran, which agent ran it and whether it succeeded. Mastra notes that the detail explaining a problem often sits deeper, in a failed tool call, a low score or thumbs-down feedback. Trace queries can reach that nested, low-level information to give a more detailed view of what happened.

Limits and supported storage

Each query covers a time range of up to 31 days and can combine up to 100 conditions. Usable fields include entityName, environment, spans.model, scores.score and feedback.value. Up to 8 filters can target trace internals (spans, scores or feedback) rather than fields on the trace itself.

The example in the announcement combines three conditions: production environment, a duration above 5000 ms, and at least one span of type tool_call that has an error. Results are ordered by start time, newest first, with a page limit of 25.

Trace queries work on the Mastra platform and on self-hosted Mastra projects where storage.observability uses DuckDB, PostgreSQL or ClickHouse.

Three ways to run a query

Requests need a platform access token and a project ID. Users must pick the observability base URL for their region: https://observability.mastra.ai for the US or https://observability.eu.mastra.ai for the EU.

• Mastra CLI: install or upgrade with npm install -g mastra@latest. It requires [email protected] or later. The mastra api trace query command reads MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID from the environment.
• Mastra Client SDK: install @mastra/client-js@latest, which requires version 1.44.0 or later, and call queryTraces() on a MastraClient.
• Observability endpoints: send a POST request to the trace query endpoint with the token and project ID in the headers.

Mastra's examples each look for agent traces from the last 7 days that ended in an error, using the conditions entityType equal to agent and status equal to error.

Available fields and operators

Conditions can be combined with and, or and not. Trace-level fields include traceId, threadId, userId, entityName, environment, status, durationMs, tags and metadata keys. Span queries, using spans.some and spans.none, cover fields such as name, spanType, model, provider, status and error. Scores and feedback have their own some and none forms, with fields like scorerId, score, feedbackType, value and comment.

Operators include eq, ne, in, notIn, lt, lte, gt, gte, exists and notExists, plus includes for tags and matches for span names and feedback comments. Pagination options and discovery helpers, getTraceQueryFields() and getTraceQueryValues(), are also available.

What it means for users

For teams running Mastra agents and workflows, the feature makes it possible to narrow a large set of traces to the specific runs where a tool failed or a model call was slow, without browsing manually. Because the same queries are exposed through the CLI, SDK and HTTP, they can be scripted or handed to a coding agent, as Mastra describes. Self-hosted users can use the feature too, provided their observability storage is DuckDB, PostgreSQL or ClickHouse.