# Tusk Drift Query

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-use-tusk-tusk-skills-tusk-drift-query`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Use-Tusk](https://agentstack.voostack.com/s/use-tusk)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [Use-Tusk](https://github.com/Use-Tusk)
- **Source:** https://github.com/Use-Tusk/tusk-skills/tree/main/skills/tusk-drift-query

## Install

```sh
agentstack add skill-use-tusk-tusk-skills-tusk-drift-query
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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`.

## Service discovery

Before running any query commands, run `tusk drift query services` to find available services.

- **0 services**: The user hasn't set up Tusk Drift cloud yet. Tell them to run `tusk drift setup` in the service of their choosing.
- **1 service**: Use that service's `id` as `--service-id` on all subsequent commands. No need to ask the user.
- **Multiple services**: STOP and ask the user which service they want to query before running any other commands. Present the list with names and repo info. Use their choice as `--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`.

## Workflow tips

- Start with `tusk drift query distinct` to discover available endpoints
- Use `tusk drift query spans` to find specific API calls
- Use `tusk drift query trace` to debug a request's full call chain

### Root cause analysis workflow

If the user is investigating performance issues or errors:

1. Use `spans` or `aggregate` to identify the problematic endpoint/span
2. Use `trace` to see the full call chain and identify which child span is the bottleneck
3. Look at the span's metadata (inputValue/outputValue) to understand the request context
4. Navigate to the relevant source code using the span name (usually maps to route handlers or functions)
5. Analyze the code path to understand the root cause

---

## Commands

### `tusk drift query distinct`

List unique values for a field, ordered by frequency.

Use this to:

- Discover available endpoints: `--field name`
- See all instrumentation packages in use: `--field packageName`
- Find unique environments: `--field environment`
- Explore JSONB values like status codes: `--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 array

---

### `tusk drift query spans`

Search and filter API traffic span recordings.

Use this to:

- Find specific API calls by endpoint name, HTTP method, or status code
- Search for errors or slow requests
- Get recent traffic for a specific endpoint
- Debug specific API calls

Examples:

- Find failed requests: `--where '{"name":{"contains":"/api/users"}}' --jsonb-filters '[{"column":"outputValue","jsonPath":"$.statusCode","gte":400,"castAs":"int"}]'`
- Find slow requests: `--min-duration 1000`
- Recent traffic for endpoint: `--name "/api/orders" --limit 10 --order-by timestamp:DESC`

**Convenience 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, name

**Advanced 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 `

Get all spans in a distributed trace as a hierarchical tree.

Use this to:

- Debug a specific request end-to-end
- See the full call chain from HTTP request to database queries
- Understand timing and dependencies between spans
- Identify bottlenecks in a request

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 length

---

### `tusk drift query aggregate`

Calculate aggregated metrics and statistics across spans.

Use this to:

- Get latency percentiles for endpoints (p50, p95, p99)
- Calculate error rates by endpoint
- Get request counts over time
- Compare performance across environments

Examples:

- Endpoint latency: `--group-by name --metrics count,avgDuration,p95Duration`
- Error rates: `--group-by name --metrics count,errorCount,errorRate`
- Hourly trends: `--time-bucket hour --metrics count,errorRate`

**Flags:**

- `--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 schema`

Get schema and structure information for span recordings.

Use this to:

- Understand what fields are available for a specific instrumentation type
- See example payloads for HTTP requests, database queries, etc.
- Learn what to filter on before querying spans

Common package names:

- http: Incoming HTTP requests (has statusCode, method, url, headers)
- fetch: Outgoing HTTP calls
- pg: PostgreSQL queries (has db.statement, db.name)
- grpc: gRPC calls
- express: Express.js middleware spans

**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 strings

---

### `tusk drift query spans-by-ids`

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

- Getting full details for spans found via `spans`
- Examining specific requests in detail
- Comparing multiple specific spans

**Flags:**

- `--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 length

---

## Error handling

- **Auth errors** (401/403): Tell the user to run `tusk auth login` or set `TUSK_API_KEY`.
- **No data returned**: The service may not have recorded traces yet. Direct them to https://docs.usetusk.ai/api-tests/record-replay-tests.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Use-Tusk](https://github.com/Use-Tusk)
- **Source:** [Use-Tusk/tusk-skills](https://github.com/Use-Tusk/tusk-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-use-tusk-tusk-skills-tusk-drift-query
- Seller: https://agentstack.voostack.com/s/use-tusk
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.