Skip to content
Speccy

List the review runs of a bundle, newest first.

GET
/docs/{docId}/runs
curl --request GET \
  --url 'https://example.com/api/v1/docs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/runs?limit=50'

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
docId
required
string format: uuid

The ID of one spec doc.

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 50 >= 1 <= 100

Responses

Section titled “ Responses ”

200

Section titled “200”

The runs.

Media typeapplication/json
object
items
required
Array<object>
object
id
required
string format: uuid
doc_id
required
string format: uuid
version_id
required
string format: uuid
version_number
required
integer format: int64
profile_key
required
string
profile_version
required
integer format: int64
kind
required
string
Allowed values: lint full
status
required
string
Allowed values: queued running complete failed
stage
required
string
error
required
string
started_at
required
string format: date-time
finished_at
string format: date-time
tokens_in
integer format: int64
tokens_out
integer format: int64
cost_estimate

USD, from the prices on the role assignments.

number
cache_hits

Steps answered from the cache (REQ-021).

integer format: int64
notes

Notes for the run report, such as “no search source configured” (REQ-034).

Array<string>
verdict

The verdict of the bundle’s latest completed run. It is stale when that run is not on the current version.

object
run_id
required
string format: uuid
version_number
required
integer format: int64
kind
required

Lint means only the lint stage ran.

string
Allowed values: lint full
result
required
string
Allowed values: build_ready not_build_ready stale
score
required
integer
radar
required
object
key
additional properties
integer
waiver_count
required
integer
relaxed_count
required

Checks in adoption mode (REQ-133).

integer
must
required

Open MUST findings.

integer
should
required
integer
info
required
integer
blocking_threads

Open blocking threads. Any makes the verdict Not Build Ready (§8.6 rule 2).

integer
ai_run_id

The full review whose AI findings this verdict counts. For a full run, the run itself.

string format: uuid
ai_version_number

The version the AI review read, when it is older than this verdict’s version.

integer format: int64
sections_changed

How many sections changed since the AI review read the doc.

integer
stale_reason

Set when the verdict is stale because a linked bundle has a newer version than the run read (REQ-056).

string
Allowed values: upstream_changed
stale_upstream

With stale_reason upstream_changed, the linked spec docs that have a newer version than the run read.

Array<object>
object
id
required
string format: uuid
bundle_id
required

The bundle that holds the spec doc.

string format: uuid
slug
required
string
title
required
string
profile_key
required
string
Example
{
  "items": [
    {
      "kind": "lint",
      "status": "queued",
      "verdict": {
        "kind": "lint",
        "result": "build_ready",
        "stale_reason": "upstream_changed"
      }
    }
  ]
}

default

Section titled “default”

An error.

Media typeapplication/problem+json

RFC 9457 problem details with a stable code.

object
type
required
string
title
required
string
status
required
integer
detail
string
instance
string
code
required

A stable machine-readable error code.

string
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example",
  "code": "example"
}