Introducing Trace Queries

You can now use trace queries to filter and find traces that match specific criteria. The Mastra platform and local Studio now let you filter by trace fields like time, primitive name, agent/workflow ID, status, score, and feedback. You (or your coding agent) can also construct the same queries using the CLI, Mastra Client SDK, and HTTP observability endpoints.

You can also let your coding agent query for traces that errored out or failed, or slow model calls, and then fix them.

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.

{
  "timeRange": {
    "from": "2026-10-01T00:00:00Z",
    "to": "2026-10-08T00:00:00Z"
  },
  "where": {
    "op": "and",
    "args": [
      { "op": "eq", "left": { "path": "environment" }, "right": { "literal": "production" } },
      { "op": "gt", "left": { "path": "durationMs" }, "right": { "literal": 5000 } },
      {
        "spans": {
          "some": {
            "op": "and",
            "args": [
              { "op": "eq", "left": { "path": "spanType" }, "right": { "literal": "tool_call" } },
              { "op": "exists", "path": "error" }
            ]
          }
        }
      }
    ]
  },
  "orderBy": [{ "field": "startedAt", "direction": "desc" }],
  "page": { "limit": 25 }
}

Each query covers a timeRange of up to 31 days and 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.

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

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 three ways to run queries: Mastra Client SDK, Mastra CLI, and observability endpoints. Each 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 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

Appendix

Fields and options available to queryTraces():

• Combine conditions: and, or, not
• Trace: traceId, threadId, resourceId, runId, sessionId, userId, organizationId, entityName, entityType, environment, status, startedAt, endedAt, durationMs, tags, metadata.<key>
• Spans (spans.some, spans.none): name, spanType, model, provider, status, error, startedAt, endedAt, durationMs, entityType, entityId, entityName, entityVersionId, parentEntityVersionId, rootEntityVersionId, runId, sessionId, userId, organizationId
• Scores (scores.some, scores.none): scorerId, scorerVersion, scoreSource, score, timestamp, spanId, entityVersionId, parentEntityVersionId, rootEntityVersionId
• Feedback (feedback.some, feedback.none): feedbackType, feedbackSource, feedbackUserId, sourceId, value, timestamp, comment, entityVersionId, parentEntityVersionId, rootEntityVersionId
• Operators: eq, ne, in, notIn, lt, lte, gt, gte, exists, notExists, includes, notIncludes (tags), matches, notMatches (span name, feedback comment)
• Pagination: page: { limit, after }, pagination: { page, perPage }, mode: 'delta'
• Discovery: getTraceQueryFields(), getTraceQueryValues()