# Spec Files

Query spec file metrics and statistics.

Get aggregated metrics for spec files within a project, including execution counts, failure rates, flakiness rates, and duration statistics.

## Get spec files

> Get spec file metrics and statistics for a project within a date range

```json
{"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Spec Files","description":"Query spec file metrics and statistics.\n\nGet aggregated metrics for spec files within a project, including execution counts,\nfailure rates, flakiness rates, and duration statistics."}],"servers":[{"url":"https://api.currents.dev/v1","description":"Production API"},{"url":"https://api-staging.currents.dev/v1","description":"Staging API"},{"url":"http://localhost:4000/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}},"parameters":{"ProjectIdPath":{"name":"projectId","in":"path","required":true,"description":"The project ID","schema":{"type":"string"}},"DateStartQuery":{"name":"date_start","in":"query","required":true,"description":"Start date in ISO 8601 format","schema":{"type":"string","format":"date-time"}},"DateEndQuery":{"name":"date_end","in":"query","required":true,"description":"End date in ISO 8601 format","schema":{"type":"string","format":"date-time"}},"PageQuery":{"name":"page","in":"query","required":false,"description":"Page number (0-indexed)","schema":{"type":"integer","minimum":0,"default":0}},"SpecFilesLimitQuery":{"name":"limit","in":"query","required":false,"description":"Maximum number of items to return (default: 50, max: 50)","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}},"TagsQuery":{"name":"tags[]","in":"query","required":false,"description":"Filter by tags (can be specified multiple times using bracket notation, e.g., tags[]=value1&tags[]=value2)","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},"BranchesQuery":{"name":"branches[]","in":"query","required":false,"description":"Filter by git branch. Use trailing `*` for prefix match (e.g. `release/*`). Max 250 characters per value.","schema":{"type":"array","items":{"$ref":"#/components/schemas/BranchFilterQueryValue"}},"style":"form","explode":true},"GroupsQuery":{"name":"groups[]","in":"query","required":false,"description":"Filter by groups (can be specified multiple times using bracket notation, e.g., groups[]=group1&groups[]=group2)","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},"AuthorsQuery":{"name":"authors[]","in":"query","required":false,"description":"Filter by git authors (can be specified multiple times using bracket notation, e.g., authors[]=author1&authors[]=author2)","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},"SortDirectionQuery":{"name":"dir","in":"query","required":false,"description":"Sort direction: `desc` (default) or `asc`.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}},"schemas":{"BranchFilterQueryValue":{"description":"Branch filter value: an exact branch name, or a trailing `*` for prefix match (e.g. `release/*`). Max 250 characters.","oneOf":[{"type":"string","description":"Exact branch name (must not contain `*` or spaces).","pattern":"^[!-)+-~]+$","maxLength":250},{"type":"string","description":"Prefix match: branch prefix followed by `*`.","pattern":"^[!-)+-~]+\\*$","maxLength":250}]},"SpecFilesResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/SpecFile"}},"total":{"type":"integer","description":"Total number of spec files"},"nextPage":{"oneOf":[{"type":"integer"},{"type":"boolean"}],"description":"Next page number or false if no more pages"}}}}},"SpecFile":{"type":"object","properties":{"signature":{"type":"string","description":"Unique spec file signature"},"spec":{"type":"string","description":"Spec file path"},"metrics":{"type":"object","properties":{"avgDuration":{"type":"number","description":"Average duration in milliseconds"},"failedExecutions":{"type":"integer"},"failureRate":{"type":"number"},"flakeRate":{"type":"number"},"flakyExecutions":{"type":"integer"},"fullyReported":{"type":"integer"},"overallExecutions":{"type":"integer"},"suiteSize":{"type":"integer"},"timeoutExecutions":{"type":"integer"},"timeoutRate":{"type":"number"}}}}},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/spec-files/{projectId}":{"get":{"summary":"Get spec files","description":"Get spec file metrics and statistics for a project within a date range","operationId":"getSpecFiles","tags":["Spec Files"],"parameters":[{"$ref":"#/components/parameters/ProjectIdPath"},{"$ref":"#/components/parameters/DateStartQuery"},{"$ref":"#/components/parameters/DateEndQuery"},{"$ref":"#/components/parameters/PageQuery"},{"$ref":"#/components/parameters/SpecFilesLimitQuery"},{"$ref":"#/components/parameters/TagsQuery"},{"$ref":"#/components/parameters/BranchesQuery"},{"$ref":"#/components/parameters/GroupsQuery"},{"$ref":"#/components/parameters/AuthorsQuery"},{"name":"order","in":"query","required":false,"description":"Field to order results by","schema":{"type":"string","enum":["avgDuration","failedExecutions","failureRate","flakeRate","flakyExecutions","fullyReported","overallExecutions","suiteSize","timeoutExecutions","timeoutRate"],"default":"avgDuration"}},{"$ref":"#/components/parameters/SortDirectionQuery"},{"name":"specNameFilter","in":"query","required":false,"description":"Filter spec files by name (partial match)","schema":{"type":"string"}},{"name":"includeFailedInDuration","in":"query","required":false,"description":"Include failed executions in duration calculation","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpecFilesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.currents.dev/api/resources/spec-files.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.