Introducing Span Queries

You can now use span queries to filter and group individual spans across all of your traces. Mastra platform and Studio support span filtering and grouping by time range, type, name, status, error, duration, and more. Your coding agent can run the same queries, then fix what it finds.

Trace queries can filter on details deep within a trace, like a failed tool call, but will return the whole trace, making problematic calls harder to spot. Span queries are more granular and search within each trace to return just the matching spans.

Span queries can be used to group or aggregate across matching spans to produce measures like counts, error rates, and latency. Use them to spot which tool is failing or slow, or to track tool latency over time, then use span queries with the same filters to inspect the problematic calls. 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, and span groups can group by up to 2 dimensions over a timeRange of up to 365 days.

Span 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

Span 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 span queries: Mastra CLI, Mastra platform and Studio, Mastra Client SDK, and observability endpoints. Each code example below groups tool calls from the last 7 days by tool, then finds the tool calls that ended in an error.

Mastra CLI

Install or upgrade the Mastra CLI globally:

npm install -g mastra@latest

Run the mastra api span aggregate command to see call count, error rate, and p95 latency for every tool. The CLI reads MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID from your environment:

mastra api --url https://observability.mastra.ai span aggregate '{
  "timeRange": { "from": "2026-10-21T00:00:00.000Z", "to": "2026-10-28T00:00:00.000Z" },
  "where": { "op": "eq", "left": { "path": "spanType" }, "right": { "literal": "tool_call" } },
  "groupBy": ["entityName"],
  "measures": ["count", "errorRate", "duration.p95"],
  "orderBy": { "field": "errorRate", "direction": "desc" }
}'

Run the mastra api span query command to find tool calls that ended in an error:

mastra api --url https://observability.mastra.ai span query '{
  "timeRange": { "from": "2026-10-21T00:00:00.000Z", "to": "2026-10-28T00:00:00.000Z" },
  "where": {
    "op": "and",
    "args": [
      { "op": "eq", "left": { "path": "spanType" }, "right": { "literal": "tool_call" } },
      { "op": "eq", "left": { "path": "status" }, "right": { "literal": "error" } }
    ]
  }
}'

Mastra platform and Studio

On Mastra platform and Studio, the Spans tab lets you filter by time range, span type, span name, status, error, duration, and more.

Mastra Client SDK

npm install @mastra/client-js@latest

import { MastraClient } from "@mastra/client-js";
 
export 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!
  }
});

Use aggregateSpans() to see call count, error rate, and p95 latency for every tool, with the worst offenders first:

import { mastraClient } from "./client";
 
const { rows } = await mastraClient.aggregateSpans({
  timeRange: {
    from: "2026-10-21T00:00:00.000Z",
    to: "2026-10-28T00:00:00.000Z"
  },
  where: {
    op: "eq",
    left: { path: "spanType" },
    right: { literal: "tool_call" }
  },
  groupBy: ["entityName"],
  measures: ["count", "errorRate", "duration.p95"],
  orderBy: { field: "errorRate", direction: "desc" }
});

Add an interval to track tool latency over time:

import { mastraClient } from "./client";
 
const { rows } = await mastraClient.aggregateSpans({
  timeRange: {
    from: "2026-10-21T00:00:00.000Z",
    to: "2026-10-28T00:00:00.000Z"
  },
  where: {
    op: "eq",
    left: { path: "spanType" },
    right: { literal: "tool_call" }
  },
  groupBy: ["entityName"],
  interval: "1d",
  measures: ["duration.p50", "duration.p95", "duration.p99"]
});

Use querySpans() to find tool calls that ended in an error:

import { mastraClient } from "./client";
 
const { spans } = await mastraClient.querySpans({
  timeRange: {
    from: "2026-10-21T00:00:00.000Z",
    to: "2026-10-28T00:00:00.000Z"
  },
  where: {
    op: "and",
    args: [
      { op: "eq", left: { path: "spanType" }, right: { literal: "tool_call" } },
      { op: "eq", left: { path: "status" }, right: { literal: "error" } }
    ]
  }
});

Observability endpoints

You can also send a POST request to the span group and span query endpoints. The request includes MASTRA_PLATFORM_ACCESS_TOKEN and MASTRA_PROJECT_ID in the headers:

For more information and full configuration options, see:

• Client SDK observability reference
• Aggregate spans reference
• mastra api span query CLI reference
• Observability on Mastra platform
• Mastra platform regions