---
title: "Read the coverage report for a table read artifact."
method: GET
path: "/artifacts/{artifactId}/coverage"
tags: ["Artifacts"]
---

# Read the coverage report for a table read artifact.

`GET /artifacts/{artifactId}/coverage`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/artifacts/{artifactId}/coverage`
- Auth: HTTP bearer

Returns the latest coverage report for the screenplay backing this artifact, or a specific report via `?reportId=<id>`. The report carries a `status` field (`generating` → `complete` / `failed`) so you can poll it to terminal. When `status: complete`, `report` carries the structured coverage payload; it is `null` while generating or on failure. `overallScore` is the GATED score: a first judgment within `judging.nearGateBand` of `gateThreshold` is followed by another, two that disagree on the bar by a third, and the score is the MEDIAN of the judgments — `summary` says so ("the median of 3 judgments"), `judging` records each one. A report the platform queues by itself (a table-read job's coverage gate and first-pass report, a season run) on a script whose text, rubric and Series Bible are identical to an earlier report's reuses that report's judgments (`judging.reusedFrom`) instead of paying for them again; a report you request (this POST) is always judged afresh. Read `verdict` for the recommendation in plain words. `scriptVersionNumber` is the SCRIPT version the report covers (`version` counts reports); `coversLatestVersion: false` means the script has moved on (`versionSummary`: "Covers v4 · the script is now v6") and the next step is coverage on the newest version. Returns `{ coverage: null }` when no coverage has been requested yet.  Scope: `artifact:read`.

## Query parameters

- `reportId` string

## Response `200`

Coverage report envelope (`coverage` may be null).

- CoverageReportEnvelope: Coverage read envelope. `coverage` is `null` when no coverage has been requested for the artifact yet.
  - `coverage` CoverageReport, required: A screenplay-rubric report from the shared coverage lifecycle for the screenplay backing a table read artifact. `report` carries the structured screenplay payload only when `status: complete`. `overallScore` is the GATED score: a first judgment within `judging.nearGateBand` of the bar is followed by another, two that disagree on the bar by a third, and the score is the MEDIAN of the judgments (`judging`); a clear pass or fail is one judgment. Read `summary` first.
    - `id` string, required
    - `artifactId` string, required
    - `status` 'generating' | 'complete' | 'failed', required: Lifecycle of an async coverage report. Poll GET /artifacts/{id}/coverage until `complete` or `failed`.
    - `version` integer, required
    - `focusPrompt` string, nullable, required: The optional focus lens supplied at generation time.
    - `progressDetail` string, nullable, required: Human-readable progress while `status: generating` (including "reading the script again" while a near-bar score is judged again).
    - `failureMessage` string, nullable, required: Why the run stopped, as one plain sentence for the writer — never a provider's or the database's raw wording. Populated when `status: failed`.
    - `overallScore` number, nullable, required: The gated score: near the bar, the MEDIAN of the judgments (`judging.median`); a clear pass or fail is one judgment. `null` unless `status: complete`.
    - `gateThreshold` number, nullable, required: The bar the report was judged against (a coverage gate's target, a season's minimum, else the default 8). `null` unless `status: complete`.
    - `gatePassed` boolean, nullable, required: Whether `overallScore` clears `gateThreshold`. `null` unless `status: complete`.
    - `judging` ScriptCoverageJudging, required: HOW A SCRIPT COVERAGE SCORE WAS REACHED. One judgment is noisy near the bar, so a first judgment within `nearGateBand` of `passMark` is judged again, up to `maxJudgments` in all, stopping as soon as a majority sit on one side of the bar; the score is the MEDIAN of `scores` (an even count reads the lower middle, so it is always a score one judgment gave, and `report` is that judgment's). A report the platform queues by itself (a table-read job's coverage gate and first-pass report, a season run) on a script whose text, rubric and Series Bible are identical to an earlier report's (`fingerprint`) reuses that report's judgments (`reusedFrom`) instead of paying for them again; a report a writer requests is always judged afresh.
      - `judgments` ScriptCoverageJudgment[], required: Every judgment, in order — including any reused from an earlier report.
        - `judgment` integer, required: 1, 2, 3 — in the order taken.
        - `reason` 'first' | 'near_bar' | 'disagreement', required: Why it was taken: the first; the judgments so far sat near the bar; or they sat on opposite sides of it.
        - `reportId` string, required: The report it was paid for (an earlier one when `reused`).
        - `reused` boolean, required: True when an earlier report of the identical script took it, and it was reused here.
        - `model` string, required
        - `judgedAt` string, date-time, required
        - `overallScore` number, nullable, required: The overall score this judgment gave.
        - `recommendation` string, nullable, required
        - `costUsd` number, required: What it cost on the usage ledger, in USD.
        - `priced` boolean, required: False when the model has no price on file and `costUsd` is the flat estimate.
      - `scores` number[], required: The scores the median was taken over, in judgment order.
      - `median` number, nullable, required: The gated score (`overallScore`). Null when no judgment gave a score.
      - `medianOf` integer, required: How many scores the median was taken over.
      - `medianJudgment` integer, nullable, required: The judgment that gave the median; its report is the one shown.
      - `medianWhy` string, required: Why that judgment is the median, in a sentence (empty for one plain judgment).
      - `passMark` number, required: The bar it was judged against.
      - `passed` boolean, required
      - `stoppedBecause` 'decisive' | 'agreement' | 'max_judgments' | 'spend_cap' | 'judgment_failed', required: `decisive`: one judgment, clear of the bar by the band; `agreement`: enough judgments sit on one side that another could not move the median across it; `max_judgments`; `spend_cap`: another was wanted but the script's extra-judgment spend cap was reached; `judgment_failed`: another was wanted but could not run.
      - `nearGateBand` number, required: Within this many points of the bar, one judgment is not trusted on its own.
      - `maxJudgments` integer, required: The most judgments one script takes.
      - `extraSpendUsd` number, required: What the judgments beyond the first cost, in USD.
      - `extraSpendCapUsd` number, required: The most the judgments beyond the first may cost for one script, in USD.
      - `fingerprint` string, nullable, required: Hash of what was judged: the script, the rubric, the Series Bible and the model.
      - `reusedFrom` object, nullable, required: The earlier report of the identical script whose judgments were reused, or null.
        - `reportId` string, required
        - `reportVersion` integer, nullable, required
    - `judgingIncomplete` object, nullable, required: A script near the bar whose median could not be completed: the further judgments it needed could not run, even queued again. The report is `failed` and is NEITHER a pass nor a fail ("Coverage couldn't finish judging — Score again"); generate coverage again. Null otherwise.
      - `judgments` integer, required: The judgments that did run.
      - `scores` number[], required: Their scores, in order.
      - `maxJudgments` integer, required
      - `passMark` number, required: The bar the script sat near.
    - `summary` string, nullable, required: The gated score in one line, e.g. "8/10 against the 8 bar — the median of 3 judgments (7 · 8 · 8)"; for an incomplete judging (`judgingIncomplete`), its sentence. `null` otherwise unless `status: complete`.
    - `verdict` string, nullable, required: The verdict in plain words, as the Coverage page leads with it: the recommendation and score, what they mean, and how the categories spread, e.g. "Consider · 7/10 — Close, but under the 8 bar: not ready to send out yet. Another pass on the top fixes should lift it. Strongest: Characters (8). Weakest: Pacing (5)." The recommendation is one rule, never the judge's own label: Recommend when the gated score clears the report's bar (`gateThreshold`), Consider within 2 points under it, Pass further under. `null` unless `status: complete`.
    - `scriptVersionNumber` integer, nullable, required: The SCRIPT version this report covers. (`version` counts reports on that script version, not script versions.)
    - `latestScriptVersionNumber` integer, nullable, required: The script's newest version.
    - `coversLatestVersion` boolean, required: `false` when the script has a newer version than the one this report covers: the report is out of date, and the one next step is coverage on the newest version (generate coverage with the script id; quote first).
    - `versionSummary` string, nullable, required: Which script version the report covers, in the Coverage page's words: "Covers v6", or "Covers v4 · the script is now v6".
    - `report` object, nullable, required: Structured coverage payload (logline, premise, structure, characters, dialogue, pacing, marketFit, overallScore, topFixes, strengths, comparable, recommendation — the same one rule `verdict` reads — judging): the report of the judgment that gave the median, whose notes are the ones to revise against. `null` unless `status: complete`.
    - `createdAt` string, date-time, required

## Other responses

- `401`: Missing, malformed, revoked, or expired API key.
- `403`: API key is valid but lacks the scope, is blocked by IP allowlist, or the account is disabled.
- `404`: The story artifact does not exist or is owned by another account.
- `409`: The artifact is not in a state where this operation is valid yet (e.g. requesting an MP4 render before the share link exists).
- `429`: Rate limit for this API key + IP + route family was exceeded.
- `500`: The API failed unexpectedly. Safe to retry with the same Idempotency-Key.

---

[API](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api.md) · [All operations](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/revisions/64c1102ccb2f?raw)