Build Filtered Views from a URL

Overview

Confident AI allows you to filter your traces, test runs, test cases and any other lists, these filters are applied in your URL parameters and can be shared with anyone. You can also build these filters manually in JSON and convert them to URLs.

This guide shows how to write that JSON, combine multiple filters, and encode the link in your language of choice — followed by a reference of everything you can filter on.

Build a filter

1. Start from a page URL

   Start with the URL of the page you want to filter. It's the same shape on every list:

   https://app.confident-ai.com/project/YOUR_PROJECT_ID/test-runs
   https://app.confident-ai.com/project/YOUR_PROJECT_ID/observatory/traces
   

   You'll add two query parameters:

   • filters — your filters as JSON, compressed (step 3 shows how).
   • operator — AND or OR, describing how multiple filter groups combine.

2. Write your filters as JSON

   Filters are organized into groups. Each group has an operator and a list of conditions, and each condition is a single filter containing a category (what you're filtering on), a condition, and a value:

   [
     {
       "operator": "AND",
       "filters": [
         { "category": "Metadata", "key": "environment", "condition": "Is", "value": "production" }
       ]
     }
   ]

   • Conditions inside a group combine using that group's operator.
   • Groups combine using the top-level operator query parameter.

   The filter reference below lists the exact category, condition, and value for every property, on each page.

3. Encode it and add to the URL

   Confident AI stores the filters value as a compressed string using the lz-string library. Compress your JSON with compressToEncodedURIComponent, then append the result as filters (it's already URL-safe) and set operator:

   https://app.confident-ai.com/project/YOUR_PROJECT_ID/test-runs?filters=COMPRESSED_STRING&operator=AND
   

   JavaScriptPythonRustRubyElixirJavaC#PHPGo

   npm install lz-string

   import LZString from "lz-string";
   
   const filters = [
     {
       operator: "AND",
       filters: [
         { category: "Metadata", key: "environment", condition: "Is", value: "production" },
       ],
     },
   ];
   
   const encoded = LZString.compressToEncodedURIComponent(JSON.stringify(filters));
   const url = `https://app.confident-ai.com/project/YOUR_PROJECT_ID/test-runs?filters=${encoded}&operator=AND`;

   Done ✅. Opening the link loads the page with the filter applied.

Filter reference

The properties you can filter on depend on the page — each page's full set is below. Two shorthands used in the tables:

• Numeric conditions — Is less than, Is equal or less than, Is greater than, Is equal or greater than, Is equal to, Does not equal.
• Tag conditions — Contains, Contains only, Does not contain.
• Everything else uses Is / Is not unless a row says otherwise.

Most properties use their category as the key. A few take a custom key — the name you're filtering on: Metadata (a metadata key), Hyperparameter (a hyperparameter name), Metric Status / Metric Score (a metric name), Criteria (a criteria name), and Classifier (a signal name).

Examples

Each example below is the filters JSON — compress it (step 3) and add it to the URL.

Filter by a metadata value. Test runs whose test cases carry environment: production:

[
  {
    "operator": "AND",
    "filters": [
      { "category": "Metadata", "key": "environment", "condition": "Is", "value": "production" }
    ]
  }
]

Filter by a hyperparameter. Test runs that used the gpt-4o value for a model hyperparameter — just the name and value, no ID:

[
  {
    "operator": "AND",
    "filters": [
      { "category": "Hyperparameter", "key": "model", "condition": "Is", "value": "gpt-4o" }
    ]
  }
]

Combine conditions in one group. Completed runs whose test cases carry environment: production — both must hold, so the group's operator is AND:

[
  {
    "operator": "AND",
    "filters": [
      { "category": "Metadata", "key": "environment", "condition": "Is", "value": "production" },
      { "category": "Status", "key": "Status", "condition": "Is", "value": "COMPLETED" }
    ]
  }
]

Combine groups with OR. Runs that are either official or have a passing Answer Relevancy metric — two groups joined by the top-level operator=OR:

[
  {
    "operator": "AND",
    "filters": [
      { "category": "Official", "key": "Official", "condition": "Is", "value": "Official" }
    ]
  },
  {
    "operator": "AND",
    "filters": [
      { "category": "Metric Status", "key": "Answer Relevancy", "condition": "Is", "value": "Passing" }
    ]
  }
]

Next Steps

Filtered links pair well with the workflows that produce the runs you're filtering.