Filtering and search

AgentMark provides a filtering system across both the Traces and Sessions pages. You can combine multiple filters, sort by any column, save filter configurations as views, and share filtered results via URL.

​

Filter popover

Click the Filters button above the trace or session list to open the filter popover. From here you can build filter expressions by adding one or more filter rows. Each filter row consists of three parts:

1. Field: the trace attribute to filter on
2. Operator: the comparison to apply
3. Value: the value to match against

Click Apply to execute the filters, or Clear to reset all filter rows.

​

Available filter fields

​

String fields

These fields support: equals, not equals, contains, not contains, starts with, and ends with.

• Model (model_used): the LLM model used for the inference (for example, gpt-5, claude-sonnet-4-20250514)
• User ID (user_id): the user identifier attached to the trace
• Prompt (prompt_name): the prompt or function name
• Session (session_id): the session identifier grouping related traces

​

Enum fields

• Status (status): filter by trace outcome. Values: OK or ERROR. Supports equals and not equals.
• Span kind (semantic_kind): filter by the semantic type of span. Values: function, llm, tool, agent, retrieval, embedding, guardrail. Supports equals and not equals.

​

Numeric fields

These fields support: equals, not equals, <, <=, >, and >=.

• Latency (ms) (latency_ms): total execution time in milliseconds
• Cost ($) (cost): the computed cost of the inference
• Prompt tokens (prompt_tokens): number of input tokens consumed
• Completion tokens (completion_tokens): number of output tokens generated

​

Content fields

These fields support contains and starts with only.

• Input (input): the prompt input text
• Output (output): the model response text

​

Tags

• Tags (tags): trace-level tag labels. Supports equals, not equals, and contains.

​

Dynamic fields

These fields are auto-populated from your application’s trace data.

• Metadata: {key} (metadata.*): any custom metadata key attached to your traces. Supports the string operators plus the existence operators (see Metadata filtering).
• Score: {name} (score__*): evaluation score names from your app’s scoring pipeline. Supports the numeric operators.

​

Date range

Both the Traces and Sessions pages include a date range selector. Use the preset ranges or define a custom window:

• Today: traces from the current day
• 7d: last 7 days
• 30d: last 30 days
• 90d: last 90 days
• Custom: pick a specific start and end date (UTC)

The date range applies alongside any active filters.

​

Column sorting

Sort any sortable column in the trace and session lists by clicking its column header. Click once to sort ascending, click again to toggle to descending. Only one sort column is active at a time.

​

Active filters bar

When you apply filters, they appear as removable chips above the results list. Each chip shows the field, operator, and value. Click the X on a chip to remove that individual filter without clearing the rest.

​

Score filtering

AgentMark automatically detects evaluation score names from your trace data and makes them available as filter fields. This lets you find traces based on quality metrics from your evaluation pipeline. To filter by score:

1. Open the filter popover
2. Select a score field (for example, Score: accuracy)
3. Choose a numeric operator (for example, >=)
4. Enter the threshold value (for example, 0.8)
5. Click Apply

​

Metadata filtering

If you attach custom metadata to your traces (via agentmark.metadata.* attributes), those keys are automatically discovered and available as filter fields. To filter by metadata:

1. Open the filter popover
2. Select a metadata field (for example, Metadata: environment)
3. Choose an operator (for example, equals)
4. Enter the value (for example, production)
5. Click Apply

You can also use the exists and does not exist operators to find traces that have (or lack) a specific metadata key, regardless of value.

​

Tag filtering

Tags are string labels attached to traces via the SDK for categorization by environment, team, feature, experiment, or release. Tags appear as a column in the trace list and are filterable through the filter popover. To filter by tags:

1. Open the filter popover
2. Select Tags from the field dropdown
3. Choose an operator and enter the tag value
4. Click Apply

You can combine tag filters with other filters (metadata, model, status) to narrow results further. The Tags field supports equals, not equals, and contains, a narrower set than most string fields. For a full guide on setting tags, naming conventions, and best practices, see the Tags documentation.

​

Sessions filtering

The Sessions page has its own filtering and search capabilities:

• Date range: the same date range selector as the Traces page (Today, 7d, 30d, 90d, Custom)
• Search: search by session ID or session name using the search bar
• Sort: sort sessions by cost, total tokens, duration, or trace count by clicking column headers
• Filter popover: the same filter builder as the Traces page, with session fields:
  • User ID (user_id): string operators (equals, not equals, contains, not contains, starts with, ends with)
  • Cost ($) (total_cost), Tokens (total_tokens), Latency (ms) (latency_ms): numeric operators
  • Tags (tags): equals, not equals, and contains

For full details on sessions, see the Sessions documentation.

​

Saved views

Use the Views dropdown to save and restore filter, sort, and date range configurations. Saved views let you quickly switch between commonly used filter sets without rebuilding them each time. To save a view:

1. Configure your desired filters, sort, and date range
2. Click the Views dropdown
3. Select Save current view
4. Give the view a name

To restore a view, open the Views dropdown and select a previously saved view. Saved views are available on both the Traces and Sessions pages.

​

URL parameters

The URL query parameters hold all filter state, including active filters, sort column, sort direction, and date range. This means you can:

• Bookmark a filtered view for quick access
• Share a URL with teammates to show them the exact same filtered results
• Link from alerts, dashboards, or external tools directly to a filtered trace list

​

Filter DSL and search API

The Dashboard filters apply to the Traces and Sessions UI, and the filter builder combines rows with AND only. The API offers the same filtering programmatically, plus OR-groups:

• Simple query parameters on GET /v1/spans filter by span type, status, model, name, duration range, user, and session. See Cross-trace span search for examples.
• The filter string DSL on GET /v1/traces and GET /v1/spans combines predicates with and and supports parenthesized OR-groups, for example (model = "gpt-5" or model = "o3") and status = ERROR. Operators match the UI builder (=, !=, >, >=, <, <=, contains, not contains, starts with, ends with, exists, does not exist), over fields including trace_id, props, metadata.<key>, and score__<name>.
• Structured JSON search via POST /v1/traces/search, POST /v1/spans/search, and POST /v1/scores/search adds in, notIn, and between operators that have no string-DSL syntax.
• GET /v1/filter-schema returns a machine-readable list of filterable fields and operators per resource. Fetch it once before constructing filters programmatically.

The same operations are available as MCP tools via the agentmark-mcp server. See the API reference for the full grammar and request schemas.

​

Next steps