> For the complete documentation index, see [llms.txt](https://docs.currents.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.currents.dev/api/resources/spec-files.md).

# 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 file metrics

> Duration percentiles, the duration histogram and the failure and flakiness rates for the spec files matching the filters, over the date range and the range of the same length before it. Pass \`signature\` for a single spec file. The filters and \`includeFailedInDuration\` behave as they do on \`GET /spec-files/{projectId}\`, so the numbers agree with the rows there. One difference from the list: a spec file that ran only in the previous range still counts toward \`previous\`, so the comparison describes what the previous range actually held.

```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":[]},{"OAuth2":["analytics:read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"An organization API key, sent as `Authorization: Bearer <key>`. A key carries one scope for the whole API: a `read` key reaches the GET endpoints, a `write` key reaches all of them. A `crnts_pat_` personal access token is accepted as a Bearer while its owner remains an eligible administrator in its active organization and the global rollout is enabled. Each operation requires the corresponding scope stored on that token."},"OAuth2":{"type":"oauth2","description":"An access token from the Currents authorization server, for an application acting as a user in one organization. Unlike an API key it is confined per endpoint: the operation lists the scope it needs, and a token that was not granted that scope gets 403.\n\n**The endpoints below are production's.** They are written out so this specification can be exercised against production, and they are wrong for every other deployment — a token minted by `id.currents.dev` is refused by a staging or on-premise API, whose `OAUTH_ISSUER` and `OAUTH_API_AUDIENCE` are its own. Against anything but production, and in a client generated from this document, discover them instead: `GET {api origin}/.well-known/oauth-protected-resource`, then the `authorization_servers[0]` document.\n\n**The audience named here is the REST API's.** `POST /mcp` is a second resource server on the same origin, identified by `{api origin}/mcp` and described by its own document at `/.well-known/oauth-protected-resource/mcp`. Every operation below refuses a token minted for it, and it refuses every token minted for these, so a client of this specification wants the audience above and not that one.","flows":{"authorizationCode":{"authorizationUrl":"https://id.currents.dev/api/auth/oauth2/authorize","tokenUrl":"https://id.currents.dev/api/auth/oauth2/token","refreshUrl":"https://id.currents.dev/api/auth/oauth2/token","scopes":{"projects:read":"See which projects exist and their names","projects:write":"Change project configuration, including a project's tags","results:read":"See runs, specs and failure detail — errors, stacks and artifacts","analytics:read":"See aggregate metrics: flake and failure rates, error counts, durations and trends","actions:read":"See quarantine and skip rules, and the tests they affect","actions:write":"Create, edit, enable, disable and archive quarantine and skip rules","issues:write":"Create and link issues in a connected issue tracker, and list its projects and issue types","runs:write":"Cancel and reset runs, and permanently delete runs and their artifacts","webhooks:read":"See webhook configuration, including destination URLs and headers","webhooks:write":"Create, edit and delete webhooks"}}}}},"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"}},"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},"EnvironmentsQuery":{"name":"environments[]","in":"query","required":false,"description":"Filter by environment (can be specified multiple times using bracket notation, e.g., environments[]=staging&environments[]=production)","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true}},"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}]},"MetricsSummary":{"type":"object","description":"Duration percentiles and outcome rates for a selection of tests or spec files, plus the duration histogram.","required":["current","previous","minMs","maxMs","distribution"],"properties":{"current":{"$ref":"#/components/schemas/PeriodMetrics"},"previous":{"allOf":[{"$ref":"#/components/schemas/PeriodMetrics"}],"description":"The range of the same length before the one asked for."},"minMs":{"type":"number","nullable":true,"description":"Shortest execution in the current range."},"maxMs":{"type":"number","nullable":true,"description":"Longest execution in the current range."},"distribution":{"type":"array","description":"Executions per duration bucket, in the current range. Buckets widen with duration; empty buckets between the first and last are included.","items":{"type":"object","required":["minMs","maxMs","executions"],"properties":{"minMs":{"type":"number"},"maxMs":{"type":"number"},"executions":{"type":"number"}}}}}},"PeriodMetrics":{"type":"object","required":["executions","overallExecutions","avgMs","p50Ms","p90Ms","p95Ms","passRate","failureRate","flakinessRate","suiteSize","testsPerExecution"],"properties":{"executions":{"type":"number","description":"Executions the duration metrics are calculated over. Narrower than `overallExecutions` when the average-duration metric setting excludes a status."},"overallExecutions":{"type":"number","description":"Executions the rates are calculated over."},"avgMs":{"type":"number","nullable":true},"p50Ms":{"type":"number","nullable":true},"p90Ms":{"type":"number","nullable":true},"p95Ms":{"type":"number","nullable":true},"passRate":{"type":"number","nullable":true,"description":"Rate as a 0-1 float. Tests only."},"failureRate":{"type":"number","nullable":true,"description":"Rate as a 0-1 float. Failures are failed and interrupted executions together."},"flakinessRate":{"type":"number","nullable":true},"suiteSize":{"type":"number","nullable":true,"description":"Tests in the most recent execution of a spec file. Null unless the metrics describe a single spec file."},"testsPerExecution":{"type":"number","nullable":true,"description":"Average tests per spec execution. Spec files only."}}},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Stable machine-readable discriminator, present on refusals a client is expected to branch on (for example `AI_CONSENT_REQUIRED`). The `error` text is free-form; branch on `code`."}}}},"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"}}}},"Forbidden":{"description":"The credential authenticated but is not permitted to use this endpoint. Four refusals share the status: a `read` API key on an endpoint that writes, an OAuth token that was not granted the scope the endpoint needs (`insufficient_scope`), an OAuth token that was granted it but whose holder no longer has a role permitting it (`insufficient_role`), and an OAuth token on an endpoint that accepts an API key and nothing else (`api_key_required`). Discriminate on `code` rather than on the message, which is free-form. The first refusal predates the codes and sets none. Only `insufficient_scope` carries the challenge header, because it is the only one a client can act on by re-authorizing.","headers":{"WWW-Authenticate":{"description":"Present on the `insufficient_scope` refusal only, naming the scope to re-authorize for (RFC 6750 3.1): `Bearer error=\"insufficient_scope\", scope=\"webhooks:read\"`. Absent on `insufficient_role`, where the scope is already granted, and on `api_key_required`, where no scope would help.","schema":{"type":"string"}}},"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}/metrics":{"get":{"summary":"Get spec file metrics","description":"Duration percentiles, the duration histogram and the failure and flakiness rates for the spec files matching the filters, over the date range and the range of the same length before it. Pass `signature` for a single spec file. The filters and `includeFailedInDuration` behave as they do on `GET /spec-files/{projectId}`, so the numbers agree with the rows there. One difference from the list: a spec file that ran only in the previous range still counts toward `previous`, so the comparison describes what the previous range actually held.","operationId":"getSpecFilesMetrics","tags":["Spec Files"],"parameters":[{"$ref":"#/components/parameters/ProjectIdPath"},{"$ref":"#/components/parameters/DateStartQuery"},{"$ref":"#/components/parameters/DateEndQuery"},{"$ref":"#/components/parameters/TagsQuery"},{"$ref":"#/components/parameters/BranchesQuery"},{"$ref":"#/components/parameters/GroupsQuery"},{"$ref":"#/components/parameters/AuthorsQuery"},{"$ref":"#/components/parameters/EnvironmentsQuery"},{"name":"signature","in":"query","required":false,"description":"Limit the metrics to one spec file","schema":{"type":"string","minLength":1}},{"name":"spec_name_filter","in":"query","required":false,"description":"Filter spec files by name (partial match). The camelCase `specNameFilter` that `GET /spec-files/{projectId}` takes is accepted too, so one query string drives the list and its metrics.","schema":{"type":"string","minLength":1}},{"name":"include_failed_in_duration","in":"query","required":false,"description":"Include failed executions in the duration calculation. The camelCase `includeFailedInDuration` is accepted too.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"$ref":"#/components/schemas/MetricsSummary"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## 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":[]},{"OAuth2":["analytics:read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"An organization API key, sent as `Authorization: Bearer <key>`. A key carries one scope for the whole API: a `read` key reaches the GET endpoints, a `write` key reaches all of them. A `crnts_pat_` personal access token is accepted as a Bearer while its owner remains an eligible administrator in its active organization and the global rollout is enabled. Each operation requires the corresponding scope stored on that token."},"OAuth2":{"type":"oauth2","description":"An access token from the Currents authorization server, for an application acting as a user in one organization. Unlike an API key it is confined per endpoint: the operation lists the scope it needs, and a token that was not granted that scope gets 403.\n\n**The endpoints below are production's.** They are written out so this specification can be exercised against production, and they are wrong for every other deployment — a token minted by `id.currents.dev` is refused by a staging or on-premise API, whose `OAUTH_ISSUER` and `OAUTH_API_AUDIENCE` are its own. Against anything but production, and in a client generated from this document, discover them instead: `GET {api origin}/.well-known/oauth-protected-resource`, then the `authorization_servers[0]` document.\n\n**The audience named here is the REST API's.** `POST /mcp` is a second resource server on the same origin, identified by `{api origin}/mcp` and described by its own document at `/.well-known/oauth-protected-resource/mcp`. Every operation below refuses a token minted for it, and it refuses every token minted for these, so a client of this specification wants the audience above and not that one.","flows":{"authorizationCode":{"authorizationUrl":"https://id.currents.dev/api/auth/oauth2/authorize","tokenUrl":"https://id.currents.dev/api/auth/oauth2/token","refreshUrl":"https://id.currents.dev/api/auth/oauth2/token","scopes":{"projects:read":"See which projects exist and their names","projects:write":"Change project configuration, including a project's tags","results:read":"See runs, specs and failure detail — errors, stacks and artifacts","analytics:read":"See aggregate metrics: flake and failure rates, error counts, durations and trends","actions:read":"See quarantine and skip rules, and the tests they affect","actions:write":"Create, edit, enable, disable and archive quarantine and skip rules","issues:write":"Create and link issues in a connected issue tracker, and list its projects and issue types","runs:write":"Cancel and reset runs, and permanently delete runs and their artifacts","webhooks:read":"See webhook configuration, including destination URLs and headers","webhooks:write":"Create, edit and delete webhooks"}}}}},"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},"EnvironmentsQuery":{"name":"environments[]","in":"query","required":false,"description":"Filter by environment (can be specified multiple times using bracket notation, e.g., environments[]=staging&environments[]=production)","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"},"code":{"type":"string","description":"Stable machine-readable discriminator, present on refusals a client is expected to branch on (for example `AI_CONSENT_REQUIRED`). The `error` text is free-form; branch on `code`."}}}},"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"}}}},"Forbidden":{"description":"The credential authenticated but is not permitted to use this endpoint. Four refusals share the status: a `read` API key on an endpoint that writes, an OAuth token that was not granted the scope the endpoint needs (`insufficient_scope`), an OAuth token that was granted it but whose holder no longer has a role permitting it (`insufficient_role`), and an OAuth token on an endpoint that accepts an API key and nothing else (`api_key_required`). Discriminate on `code` rather than on the message, which is free-form. The first refusal predates the codes and sets none. Only `insufficient_scope` carries the challenge header, because it is the only one a client can act on by re-authorizing.","headers":{"WWW-Authenticate":{"description":"Present on the `insufficient_scope` refusal only, naming the scope to re-authorize for (RFC 6750 3.1): `Bearer error=\"insufficient_scope\", scope=\"webhooks:read\"`. Absent on `insufficient_role`, where the scope is already granted, and on `api_key_required`, where no scope would help.","schema":{"type":"string"}}},"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"},{"$ref":"#/components/parameters/EnvironmentsQuery"},{"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"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.