Filtering and search

Documentation Index

Fetch the complete documentation index at: https://docs.agentmark.co/llms.txt

Use this file to discover all available pages before exploring further.

AgentMark provides a comprehensive 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 (e.g., gpt-4o, 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 exists and does not exist.
• 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

Sortable columns in the trace and session lists can be sorted by clicking the 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 filters are applied, 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 (e.g., Score: accuracy)
3. Choose a numeric operator (e.g., >=)
4. Enter the threshold value (e.g., 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 (e.g., Metadata: environment)
3. Choose an operator (e.g., equals)
4. Enter the value (e.g., 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
• User filter — filter sessions by user ID to see all sessions for a specific user

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

All filter state — including active filters, sort column, sort direction, and date range — is persisted in URL query parameters. 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

​

Programmatic span search

The Dashboard filters apply to the Traces and Sessions UI. To search spans programmatically across all traces, use the GET /v1/spans endpoint or the npx agentmark api spans list CLI command. This lets you filter by span type, status, model, name, and duration range without browsing individual traces. See Cross-trace span search for examples and available filters, or the API reference for the full endpoint specification.

​

Next steps