> ## Documentation Index > Fetch the complete documentation index at: https://docs.testdino.com/llms.txt > Use this file to discover all available pages before exploring further. # Explore test cases with aggregated metrics > Returns a paginated list of test cases with aggregated metrics across multiple runs, including pass rate, fail rate, flakiness rate, average duration, and last execution time. Useful for identifying consistently failing, slow, or flaky tests over a configurable lookback period. Filter by spec file, platform, environment, status, or tags. ## OpenAPI ````yaml /api-reference/openapi.yml get /{projectId}/test-case-explorer openapi: 3.0.3 info: title: TestDino Public API version: 1.0.0 description: > Public API for TestDino — read-only access to test analytics, manual tests, and project data. **17 read-only GET endpoints** organized into 12 sections. Query parameters are **endpoint-specific** — see each operation for supported filters, enums, and defaults. ## Authentication All endpoints require a Bearer token in the `Authorization` header: ``` Authorization: Bearer td_pat_ ``` Use a user PAT (`td_pat_` prefix) scoped to the organization/project. ## Rate Limiting - **Per-token:** 100 requests/minute - **Per-IP (pre-auth):** 200 requests/minute - **PDF generation:** 1 request/minute per token Standard headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` ## Response Format **Success:** ```json { "success": true, "data": { ... }, "pagination": { ... } } ``` **Error:** ```json { "success": false, "error": { "code": "ERROR_CODE", "message": "Human-readable message" } } ``` ## Time windows and date filters There is **no global date-filter convention**. Each endpoint documents its own parameters: | Endpoint family | Parameter | Allowed values | |-----------------|-----------|------------------| | Test runs list | `start_date`, `end_date` | RFC3339 timestamps (both required together) | | Explorer, specs, analytics | `days` | Integer snapped to **7, 30, or 90** (see each endpoint) | | Test runs list | — | No preset `period` / `dateRange` params | | Dashboard, filters | — | **No query params** (fixed downstream snapshot) | ## Served by This contract is served by the **MCP service** (the gateway), which authenticates the `td_pat_` user PAT and fans out to data-handler / tcm / user-service / billing. It is **read-only** — webhook subscription management (the previous public API's only write surface) is owned by the **integration service** and is not part of this contract. ## Implementation status All 17 routes are mounted (auth + rate-limit). Most call their real downstream today; a few still have lean shapes or pending owners (notably `usage` → billing). Live vs pending detail: `docs/DOWNSTREAM_WORK.md`. contact: name: TestDino Support url: https://docs.testdino.com servers: - url: https://api.testdino.com/api/v1/public description: Production security: - BearerAuth: [] tags: - name: Token Info description: Token introspection and project metadata - name: Test Runs description: List, inspect, and drill into test runs - name: Test Cases description: Automated test case details and history - name: Specs description: Project-level spec file health - name: Manual Tests description: Manual test suites and cases (read-only) - name: Test Case Explorer description: Aggregated test case metrics explorer - name: Context description: >- Debugging payload at three levels (run / suite / test) — error, steps, failure window, attempts, attachments, trace, deep links, and a copy-paste retry command. Designed for AI agents and CI scripts. - name: Dashboard description: Project health overview - name: Filters description: Available filter values (environments, branches, developers, tags) - name: Reports description: PDF report generation and download - name: Analytics description: Consolidated analytics summary and test case execution performance - name: Usage description: Subscription usage and limits paths: /{projectId}/test-case-explorer: get: tags: - Test Case Explorer summary: Explore test cases with aggregated metrics description: > Returns a paginated list of test cases with aggregated metrics across multiple runs, including pass rate, fail rate, flakiness rate, average duration, and last execution time. Useful for identifying consistently failing, slow, or flaky tests over a configurable lookback period. Filter by spec file, platform, environment, status, or tags. parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/page' - name: limit in: query schema: type: integer enum: - 10 - 25 - 50 default: 25 description: >- Page size. Must be one of `10`, `25`, or `50` (default `25`). Any other value returns `400 INVALID_LIMIT`. - name: status in: query schema: type: string enum: - flaky - chronic - stable description: Filter by behavioral status class. `stable` requires `days=90`. - name: specFilePath in: query schema: type: string description: Filter to test cases from a specific spec file path. - name: platform in: query schema: type: string description: Filter by test platform (e.g. `chromium`, `firefox`, `webkit`). - $ref: '#/components/parameters/environment' - name: tags in: query schema: type: string description: >- Single tag string (maps to downstream `tag`). Not comma-separated multi-tag. - name: days in: query schema: type: integer enum: - 7 - 30 - 90 default: 30 description: >- Rolling window in days. Must be 7, 30, or 90 (default 30). Other values return 400 downstream. - name: search in: query schema: type: string description: Free-text search across test case names. - name: sortBy in: query schema: type: string enum: - suite_file_path - title - flaky_rate - failure_rate - reliability_score - total_runs - p95_duration_ms - duration_trend_slope - consecutive_failure_streak - last_seen_at - last_duration_ms - avg_duration_ms default: suite_file_path description: >- Sort field (maps to downstream `sort`). Default `suite_file_path`. Sort-dependent default direction applies when `order` is omitted. - name: order in: query schema: type: string enum: - asc - desc description: >- Sort direction (maps to downstream `dir`). Default depends on `sortBy` — text sorts default `asc`, metrics default `desc`. responses: '200': description: Aggregated test case data content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope' '401': $ref: '#/components/responses/Unauthorized' components: parameters: projectId: name: projectId in: path required: true schema: type: string description: >- The project identifier (e.g. `project_abc123`). Must match the project associated with your PAT. page: name: page in: query schema: type: integer minimum: 1 default: 1 description: Page number for paginated results. Starts at 1. environment: name: environment in: query schema: type: string description: >- Filter results by environment name (e.g. `production`, `staging`). Use the `/filters` endpoint to discover available environments. schemas: SuccessEnvelope: type: object properties: success: type: boolean enum: - true data: type: object pagination: $ref: '#/components/schemas/Pagination' Pagination: type: object properties: page: type: integer limit: type: integer total: type: integer hasNext: type: boolean hasPrev: type: boolean ErrorEnvelope: type: object properties: success: type: boolean enum: - false error: type: object properties: code: type: string message: type: string responses: Unauthorized: description: Missing, invalid, expired, or revoked token content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: success: false error: code: AUTH_INVALID_TOKEN message: Invalid or expired token securitySchemes: BearerAuth: type: http scheme: bearer description: User PAT (td_pat_) scoped to the target project ````