> ## 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. # List test runs with filtering and pagination > Returns a paginated list of test runs for the project. Default sort is **`counter_desc`** (newest counter first). Query parameter names match the data-handler `/runs` endpoint (snake_case). **Date range:** pass **`start_date`** and **`end_date`** together as RFC3339 timestamps (e.g. `2026-03-01T00:00:00Z`). There is no `period` or camelCase date alias. ## OpenAPI ````yaml /api-reference/openapi.yml get /{projectId}/test-runs 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-runs: get: tags: - Test Runs summary: List test runs with filtering and pagination description: > Returns a paginated list of test runs for the project. Default sort is **`counter_desc`** (newest counter first). Query parameter names match the data-handler `/runs` endpoint (snake_case). **Date range:** pass **`start_date`** and **`end_date`** together as RFC3339 timestamps (e.g. `2026-03-01T00:00:00Z`). There is no `period` or camelCase date alias. parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/limit' - name: status in: query schema: type: string enum: - passed - failed - interrupted - incomplete - running description: Filter by run status. CSV allowed (e.g. `failed,interrupted`). - name: branch in: query schema: type: string description: Filter by git branch (CSV allowed). - name: environment in: query schema: type: string description: Filter by environment name (must exist for this project). - name: author in: query schema: type: string description: Filter by git commit author (CSV allowed). - name: run_tags in: query schema: type: string description: Comma-separated run-level tags (e.g. `smoke,prod`). - name: test_case_tags in: query schema: type: string description: Comma-separated test-case tags that must appear on cases in the run. - name: tag_match in: query schema: type: string enum: - exact description: When set to `exact`, tag filters require an exact tag match. - name: search in: query schema: type: string description: Free-text search across commit messages and run counter numbers. - name: start_date in: query schema: type: string format: date-time description: Start of run time window (RFC3339). Must be used with `end_date`. - name: end_date in: query schema: type: string format: date-time description: End of run time window (RFC3339). Must be used with `start_date`. - name: sort in: query schema: type: string enum: - counter_desc - counter_asc - duration_asc - duration_desc default: counter_desc description: Sort order for the run list. responses: '200': description: Paginated list of test runs content: application/json: schema: type: object properties: success: type: boolean data: type: array items: $ref: '#/components/schemas/TestRunListItem' pagination: $ref: '#/components/schemas/Pagination' '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. limit: name: limit in: query schema: type: integer enum: - 10 - 25 - 50 - 100 default: 10 description: >- Page size. Must be one of `10`, `25`, `50`, or `100` (default `10`). Any other value returns `400 INVALID_LIMIT`. schemas: TestRunListItem: type: object properties: id: type: string counter: type: integer status: type: string enum: - passed - failed - interrupted - incomplete - running startTime: type: string format: date-time endTime: type: string format: date-time duration: type: integer testStats: $ref: '#/components/schemas/TestStats' metadata: type: object properties: git: $ref: '#/components/schemas/GitMetadata' url: type: string description: Deep-link to the test run in the TestDino UI Pagination: type: object properties: page: type: integer limit: type: integer total: type: integer hasNext: type: boolean hasPrev: type: boolean TestStats: type: object properties: total: type: integer passed: type: integer failed: type: integer skipped: type: integer flaky: type: integer timedOut: type: integer totalAttempts: type: integer retriedTests: type: integer GitMetadata: type: object properties: branch: type: string environment: type: string commit: type: object properties: hash: type: string message: type: string author: type: string 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 ````