---
title: "Read a portrait design's casting coverage."
method: GET
path: "/story-projects/{projectId}/cast-portraits/designs/{designId}/coverage"
tags: ["Projects"]
---

# Read a portrait design's casting coverage.

`GET /story-projects/{projectId}/cast-portraits/designs/{designId}/coverage`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/story-projects/{projectId}/cast-portraits/designs/{designId}/coverage`
- Auth: HTTP bearer

A model looked at every drawn headshot blind, beside the faces already chosen for the cast, and scored each on emblematic fit, period truth, naturalness (not generated) and distinctness; answers the ranking, each headshot's score and flags, the recommendation, `failingCandidates` and — when every one failed — a revised look. A design with no report reads `missing`, not 404. Free. Scope: `story:read`.

## Response `200`

The portrait casting coverage.

- CastingPortraitCoverageResponse
  - `coverage` CastingPortraitCoverage, required: PORTRAIT CASTING COVERAGE of a portrait design: a model looked at every drawn headshot blind, beside the faces already chosen for the cast, and scored each on emblematic fit, period truth, naturalness (not generated) and distinctness. Choosing a headshot in `failingCandidates` is refused unless the writer chooses it anyway.
    - `status` 'missing' | 'generating' | 'complete' | 'failed', required
    - `kind` 'portrait', required
    - `projectId` string, required
    - `designId` string, required
    - `character` string, required
    - `keyCharacter` boolean, required
    - `available` boolean, required
    - `gateThreshold` number, required
    - `vetoDimensions` string[], required
    - `recommended` integer, nullable, required
    - `failingCandidates` integer[], required
    - `summary` string, required
    - `trigger` 'auto' | 'manual' | 'null', nullable, required
    - `reportId` string, nullable, required
    - `reportVersion` integer, nullable, required
    - `rubricVersion` integer, nullable, required
    - `model` string, nullable, required
    - `progressDetail` string, nullable, required
    - `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`.
    - `report` object, nullable, required: The ranking, every headshot (`candidate`, `candidateId`, `imageUrl`, `score`, `passed`, `flags`, `dimensions`, `problems`, `closestCastFace`), `recommended`, `runnerUp`, `close`, `allFail`, `redesign` ({ why, revisedDirection }), `verdict`, `references` and `judging`.
    - `createdAt` string, date-time, nullable, required
    - `updatedAt` string, date-time, nullable, 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`: No portrait design with that id in this project (`portrait_design_not_found`), or the project is not yours (`project_not_found`).
- `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/86e084144cef?raw)