Query Parameters
Overview
The testing-api utilizes query parameters to enable flexible data retrieval. These parameters allow you to refine your requests through pagination, sorting, and conditional filtering. Parameters are appended to the endpoint URL using standard URI syntax (e.g., ?limit=10&offset=0).
Global Parameters
The following parameters are supported across all collection-based endpoints (GET requests) within the Supervised AI platform.
Pagination
To manage large datasets and improve performance, use the following pagination parameters:
| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| limit | integer | 20 | The maximum number of records to return in a single response. Max value is 100. |
| offset | integer | 0 | The number of records to skip before starting to return results. |
| page | integer | 1 | (Optional) Alternative to offset; specifies the page number based on the limit. |
Example Usage:
GET /v1/tests?limit=50&offset=100
Sorting
Control the order of the returned results using the sort and order parameters.
| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| sort_by | string | created_at | The field name to sort the results by (e.g., updated_at, status, name). |
| order | string | desc | The direction of the sort. Supported values: asc (ascending) or desc (descending). |
Example Usage:
GET /v1/test-suites?sort_by=updated_at&order=asc
Filtering
Filters allow you to narrow down results based on specific resource attributes. Filters can be combined to create complex queries.
Common Filter Parameters
| Parameter | Type | Description |
| :--- | :--- | :--- |
| status | string | Filter by resource state (e.g., queued, running, completed, failed). |
| tags | string | A comma-separated list of tags associated with the resource. |
| created_after | ISO-8601 | Return resources created after a specific timestamp. |
| created_before | ISO-8601 | Return resources created before a specific timestamp. |
| search | string | Perform a partial match search on names or descriptions. |
Endpoint-Specific Filters
In addition to global filters, specific endpoints support unique parameters relevant to their resource type:
/v1/tests
model_id: Filter tests associated with a specific AI model version.dataset_id: Filter results generated from a specific input dataset.result: Filter by outcome (e.g.,pass,fail,uncertain).
/v1/deployments
environment: Filter by deployment target (e.g.,production,staging,sandbox).active:booleanto return only currently running deployments.
Usage Examples
Combining Multiple Parameters
To retrieve the 10 most recent failed tests for a specific model:
GET /v1/tests?limit=10&sort_by=created_at&order=desc&status=failed&model_id=mod_88234
Searching and Tag Filtering
To find all datasets tagged with "vision" that match the term "training":
GET /v1/datasets?tags=vision&search=training
Parameter Validation Errors
If an invalid parameter type or value is provided, the API will return a 400 Bad Request status code with a JSON body detailing the error:
{
"error": "validation_failed",
"message": "The 'limit' parameter must be an integer between 1 and 100.",
"fields": {
"limit": "invalid_type"
}
}