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

get

/spec-files/{projectId}/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.

Authorizations

AuthorizationstringRequired

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. Each operation requires the corresponding scope stored on that token.

Path parameters

projectIdstringRequired

The project ID

Example: proj_abc123

Query parameters

date_startstring · date-timeRequired

Start date in ISO 8601 format

Example: 2024-01-01T00:00:00.000Z

date_endstring · date-timeRequired

End date in ISO 8601 format

Example: 2024-01-31T23:59:59.999Z

tags[]string[]Optional

Filter by tags (can be specified multiple times using bracket notation, e.g., tags[]=value1&tags[]=value2)

Example: ["tag1","tag2"]

groups[]string[]Optional

Filter by groups (can be specified multiple times using bracket notation, e.g., groups[]=group1&groups[]=group2)

Example: ["group1","group2"]

authors[]string[]Optional

Filter by git authors (can be specified multiple times using bracket notation, e.g., authors[]=author1&authors[]=author2)

Example: ["author1","author2"]

environments[]string[]Optional

Filter by environment (can be specified multiple times using bracket notation, e.g., environments[]=staging&environments[]=production)

Example: ["staging","production"]

signaturestring · min: 1Optional

Limit the metrics to one spec file

spec_name_filterstring · min: 1Optional

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.

include_failed_in_durationbooleanOptional

Include failed executions in the duration calculation. The camelCase includeFailedInDuration is accepted too.

Default: false

Responses

200

Successful response

application/json

statusstring · enumRequiredPossible values:

400

Invalid request parameters

application/json

401

Authentication failed

application/json

403

The credential authenticated but is not permitted to use this endpoint. Five 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), an OAuth token on an endpoint that accepts an API key and nothing else (api_key_required), and an API key on an endpoint that answers for a user (user_credential_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.

application/json

404

Resource not found

application/json

get/spec-files/{projectId}/metrics

GET /v1/spec-files/{projectId}/metrics?date_start=2026-01-01T00%3A00%3A00.000Z&date_end=2026-01-01T00%3A00%3A00.000Z HTTP/1.1
Host: api.currents.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "status": "OK",
  "data": {
    "current": {
      "executions": 1,
      "overallExecutions": 1,
      "avgMs": 1,
      "p50Ms": 1,
      "p90Ms": 1,
      "p95Ms": 1,
      "passRate": 1,
      "failureRate": 1,
      "flakinessRate": 1,
      "suiteSize": 1,
      "testsPerExecution": 1
    },
    "previous": {
      "executions": 1,
      "overallExecutions": 1,
      "avgMs": 1,
      "p50Ms": 1,
      "p90Ms": 1,
      "p95Ms": 1,
      "passRate": 1,
      "failureRate": 1,
      "flakinessRate": 1,
      "suiteSize": 1,
      "testsPerExecution": 1
    },
    "minMs": 1,
    "maxMs": 1,
    "distribution": [
      {
        "minMs": 1,
        "maxMs": 1,
        "executions": 1
      }
    ]
  }
}

Get spec files

get

/spec-files/{projectId}

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

Authorizations

AuthorizationstringRequired

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. Each operation requires the corresponding scope stored on that token.

Path parameters

projectIdstringRequired

The project ID

Example: proj_abc123

Query parameters

date_startstring · date-timeRequired

Start date in ISO 8601 format

Example: 2024-01-01T00:00:00.000Z

date_endstring · date-timeRequired

End date in ISO 8601 format

Example: 2024-01-31T23:59:59.999Z

pageintegerOptional

Page number (0-indexed)

Default: 0

limitinteger · min: 1 · max: 50Optional

Maximum number of items to return (default: 50, max: 50)

Default: 50

tags[]string[]Optional

Filter by tags (can be specified multiple times using bracket notation, e.g., tags[]=value1&tags[]=value2)

Example: ["tag1","tag2"]

groups[]string[]Optional

Filter by groups (can be specified multiple times using bracket notation, e.g., groups[]=group1&groups[]=group2)

Example: ["group1","group2"]

authors[]string[]Optional

Filter by git authors (can be specified multiple times using bracket notation, e.g., authors[]=author1&authors[]=author2)

Example: ["author1","author2"]

environments[]string[]Optional

Filter by environment (can be specified multiple times using bracket notation, e.g., environments[]=staging&environments[]=production)

Example: ["staging","production"]

orderstring · enumOptional

Field to order results by

Default: avgDurationPossible values:

dirstring · enumOptional

Sort direction: desc (default) or asc.

Default: descPossible values:

specNameFilterstringOptional

Filter spec files by name (partial match)

includeFailedInDurationbooleanOptional

Include failed executions in duration calculation

Default: false

Responses

200

Successful response

application/json

statusstring · enumRequiredPossible values:

400

Invalid request parameters

application/json

401

Authentication failed

application/json

403

The credential authenticated but is not permitted to use this endpoint. Five 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), an OAuth token on an endpoint that accepts an API key and nothing else (api_key_required), and an API key on an endpoint that answers for a user (user_credential_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.

application/json

404

Resource not found

application/json

get/spec-files/{projectId}

GET /v1/spec-files/{projectId}?date_start=2026-01-01T00%3A00%3A00.000Z&date_end=2026-01-01T00%3A00%3A00.000Z HTTP/1.1
Host: api.currents.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "status": "OK",
  "data": {
    "list": [
      {
        "signature": "text",
        "spec": "text",
        "metrics": {
          "avgDuration": 1,
          "failedExecutions": 1,
          "failureRate": 1,
          "flakeRate": 1,
          "flakyExecutions": 1,
          "fullyReported": 1,
          "overallExecutions": 1,
          "suiteSize": 1,
          "timeoutExecutions": 1,
          "timeoutRate": 1
        }
      }
    ],
    "total": 1,
    "nextPage": 1
  }
}