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. Useascfor ascending ordescfor 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