// Search, analyze, and debug recorded API traffic using the Tusk Drift CLI query commands. Use when users want to explore their API endpoints, investigate errors or latency, trace requests, or understand traffic patterns.
| name | tusk-drift-query |
| description | Search, analyze, and debug recorded API traffic using the Tusk Drift CLI query commands. Use when users want to explore their API endpoints, investigate errors or latency, trace requests, or understand traffic patterns. |
| allowed-tools | Bash(tusk drift query:*) |
Search and analyze API traffic span recordings from Tusk Drift using CLI commands.
These commands help you query, analyze, and debug API traffic including HTTP requests/responses, database queries, gRPC calls, and more — latency metrics, error rates, and distributed traces across services.
All commands output JSON to stdout. All accept --service-id to override the default from .tusk/config.yaml.
Before running any query commands, run tusk drift query services to find available services.
tusk drift setup in the service of their choosing.id as --service-id on all subsequent commands. No need to ask the user.--service-id on all subsequent commands.If tusk drift query services fails with an auth error, tell the user to run tusk auth login or set TUSK_API_KEY.
tusk drift query distinct to discover available endpointstusk drift query spans to find specific API callstusk drift query trace to debug a request's full call chainIf the user is investigating performance issues or errors:
spans or aggregate to identify the problematic endpoint/spantrace to see the full call chain and identify which child span is the bottlenecktusk drift query distinctList unique values for a field, ordered by frequency.
Use this to:
--field name--field packageName--field environment--field "outputValue.statusCode"This helps you understand what values exist before building specific queries.
Flags:
--field (required) — Field to get distinct values for. Can be a column name or JSONB path (e.g., name, packageName, outputValue.statusCode)--limit (default 50) — Max distinct values to return (1-100)--where — Optional filter conditions as JSON (SpanWhereClause)--jsonb-filters — Optional JSONB filters as JSON arraytusk drift query spansSearch and filter API traffic span recordings.
Use this to:
Examples:
--where '{"name":{"contains":"/api/users"}}' --jsonb-filters '[{"column":"outputValue","jsonPath":"$.statusCode","gte":400,"castAs":"int"}]'--min-duration 1000--name "/api/orders" --limit 10 --order-by timestamp:DESCConvenience flags:
--name — Filter by span/endpoint name (exact match)--package-name — Filter by instrumentation package (http, pg, fetch, grpc, etc.)--trace-id — Filter by trace ID--environment — Filter by environment--min-duration — Minimum duration in milliseconds--root-spans-only — Only return root spans--limit (default 20) — Max results (1-100)--offset (default 0) — Pagination offset--include-payloads (default false) — Include full inputValue/outputValue (can be verbose)--max-payload-length (default 500) — Truncate payload strings to this length--order-by — Sort results, format field:direction (e.g., timestamp:DESC, duration:ASC). Fields: timestamp, duration, nameAdvanced flags (JSON strings, override convenience flags):
--where — Full SpanWhereClause as JSON. Supports field filters (name, packageName, instrumentationName, environment, traceId, spanId, duration, isRootSpan) with operators (eq, neq, in, contains, startsWith, endsWith, gt, gte, lt, lte). Supports AND/OR arrays for combining conditions.--jsonb-filters — Array of JSONB filters as JSON. Each filter has: column (inputValue, outputValue, metadata, status), jsonPath (starting with $, e.g., $.statusCode), comparison operators (eq, neq, gt, gte, lt, lte, contains, startsWith, endsWith, isNull, in), and optional castAs (text, int, float, boolean).tusk drift query trace <trace-id>Get all spans in a distributed trace as a hierarchical tree.
Use this to:
First use spans to find spans, then use the traceId from the results to get the full trace.
Flags:
--include-payloads (default false) — Include inputValue/outputValue--max-payload-length (default 500) — Truncate payload strings to this lengthtusk drift query aggregateCalculate aggregated metrics and statistics across spans.
Use this to:
Examples:
--group-by name --metrics count,avgDuration,p95Duration--group-by name --metrics count,errorCount,errorRate--time-bucket hour --metrics count,errorRateFlags:
--metrics (required) — Metrics to calculate, comma-separated. Values: count, errorCount, errorRate, avgDuration, minDuration, maxDuration, p50Duration, p95Duration, p99Duration--group-by — Fields to group by, comma-separated. Values: name, packageName, instrumentationName, environment, statusCode--time-bucket — Time bucket for time-series data: hour, day, week--order-by — Order by metric, format metric:direction (e.g., count:DESC)--limit (default 20) — Max results (1-100)--where — Filter conditions as JSON (SpanWhereClause)tusk drift query schemaGet schema and structure information for span recordings.
Use this to:
Common package names:
Flags:
--name — Span name to get schema for (e.g., /api/users)--package-name — Package name (e.g., http, pg, fetch)--instrumentation-name — Specific instrumentation name--show-example (default true) — Include an example span with real data--max-payload-length (default 500) — Truncate example payload stringstusk drift query spans-by-idsFetch specific span recordings by their IDs.
Use this when you have span IDs from a previous query and need the full details including payloads. Useful for:
spansFlags:
--ids (required) — Span recording IDs, comma-separated (max 20)--include-payloads (default true) — Include full inputValue/outputValue--max-payload-length (default 500) — Truncate payload strings to this lengthtusk auth login or set TUSK_API_KEY.Analyze Tusk Drift API test deviations locally — classifies deviations as intended, unintended, or unrelated, and optionally fixes regressions.
Discover and selectively adopt existing Tusk-generated unit tests. Only relevant once a branch has been pushed and a PR exists — Tusk generates runs in CI on PR push, not for unpushed local work. Use when iterating on a PR, reviewing CI, or when the user asks about adding the Tusk-generated tests for their current branch.