Query & Filtering

Querying and Filtering

The Supervised AI testing API provides a robust set of query parameters to help you interact with large datasets. You can refine your requests by filtering on specific attributes, sorting the result sets, and paginating through records.

Filtering

Filters allow you to narrow down the results returned by an endpoint. To apply a filter, append the attribute name and the desired value as a query parameter to the request URL.

Basic Filtering Filters are applied using the syntax ?field=value. Multiple filters can be combined using the & operator (treated as a logical AND).

GET /v1/tests?status=completed&priority=high

Supported Filter Operators For numeric or date fields, you can use bracketed operators to perform range queries:

| Operator | Description | Example | | :--- | :--- | :--- | | [gt] | Greater than | created_at[gt]=2023-01-01 | | [gte] | Greater than or equal to | score[gte]=90 | | [lt] | Less than | duration[lt]=500 | | [lte] | Less than or equal to | updated_at[lte]=2023-12-31 | | [ne] | Not equal to | type[ne]=benchmark |

Example: Range Query

GET /v1/test-runs?accuracy[gte]=0.85&accuracy[lte]=0.99

Sorting

You can control the order in which items are returned using the sort and order parameters.

• sort: The field name to sort by (e.g., created_at, name, id).
• order: The direction of the sort. Use asc for ascending or desc for descending.

Example: Sorting by Most Recent

GET /v1/results?sort=created_at&order=desc

Note: If no sort parameters are provided, the API typically defaults to created_at in descending order.

Pagination

To maintain performance and reduce latency, the API paginates all list responses. Use the following parameters to navigate through the data:

| Parameter | Type | Default | Description | | :--- | :--- | :--- | :--- | | page | Integer | 1 | The page number to retrieve. | | limit | Integer | 20 | The number of records to return per page (Max: 100). |

Example: Requesting the Second Page

GET /v1/datasets?page=2&limit=50

Response Metadata When a list is paginated, the response body includes a meta object to help you manage state:

{
  "data": [...],
  "meta": {
    "current_page": 2,
    "total_pages": 10,
    "total_count": 500,
    "limit": 50
  }
}

Combining Parameters

All query parameters can be used simultaneously to create highly specific data fetches.

Example: Complex Query Fetch the top 10 highest-scoring "production" tests, paginated:

GET /v1/tests?environment=production&sort=score&order=desc&limit=10&page=1