Introducing Trace Queries

You can now use trace queries to filter and find traces that match specific criteria. Mastra platform and Studio support trace filtering by time range, primitive type, environment, status, score, feedback, and more. Your coding agent can run the same queries, then fix what it finds.

Trace queries usually match fields on the trace itself: when it ran, which agent ran it, and whether it succeeded. The detail that explains a problem often sits deeper, in a failed tool call, a low score, or thumbs-down feedback. Trace queries can reach low-level information nested deep within a trace to provide a more detailed view of what really happened.

Each query can combine up to 100 conditions, using fields like entityName, environment, spans.model, scores.score, and feedback.value, with up to 8 filters on trace internals (spans, scores, or feedback) rather than fields on the trace itself. A query's timeRange can cover any of your retained trace data, as long as from is earlier than to; the 31-day maximum was removed in @mastra/core 1.78.0.

Trace queries work on Mastra platform and on self-hosted Mastra projects where storage.observability uses DuckDB, PostgreSQL, or ClickHouse. If your trace data lives outside of Mastra, you can bring your existing history over with trace imports.

Get started

Trace 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:

• US: https://observability.mastra.ai
• EU: https://observability.eu.mastra.ai

There are four ways to run queries: Mastra CLI, Mastra platform and Studio, Mastra Client SDK, and observability endpoints. Each code example below finds agent traces from the last 7 days that ended in an error.

Mastra CLI

Install or upgrade the Mastra CLI globally:

npm install -g mastra@latest

Run the mastra api trace query command from your terminal. The CLI reads MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID from your environment:

mastra api --url https://observability.mastra.ai trace query '{
  "timeRange": { "from": "2026-10-07T00:00:00.000Z", "to": "2026-10-14T00:00:00.000Z" },
  "where": {
    "op": "and",
    "args": [
      { "op": "eq", "left": { "path": "entityType" }, "right": { "literal": "agent" } },
      { "op": "eq", "left": { "path": "status" }, "right": { "literal": "error" } }
    ]
  }
}'

Mastra platform and Studio

On Mastra platform and Studio, the Traces tab lets you filter by time range, primitive type, environment, status, score, feedback, and more.

Mastra Client SDK

Use queryTraces() with MastraClient:

npm install @mastra/client-js@latest

import { MastraClient } from "@mastra/client-js";
 
const mastraClient = new MastraClient({
  baseUrl: "https://observability.mastra.ai",
  headers: {
    Authorization: `Bearer ${process.env.MASTRA_PLATFORM_ACCESS_TOKEN}`,
    "X-Mastra-Project-Id": process.env.MASTRA_PROJECT_ID!
  }
});
 
const { traces } = await mastraClient.queryTraces({
  timeRange: {
    from: "2026-10-07T00:00:00.000Z",
    to: "2026-10-14T00:00:00.000Z"
  },
  where: {
    op: "and",
    args: [
      { op: "eq", left: { path: "entityType" }, right: { literal: "agent" } },
      { op: "eq", left: { path: "status" }, right: { literal: "error" } }
    ]
  }
});

Observability endpoints

You can also send a POST request using the trace query endpoint. The request includes MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID variables in the headers:

For more information and full configuration options, see:

• Advanced trace queries reference
• Client SDK observability reference
• mastra api trace query CLI reference
• Observability on Mastra platform
• Mastra platform regions