---
title: "One storyboard"
method: GET
path: "/storyboards/{id}"
tags: ["storyboards"]
---

# One storyboard

`GET /storyboards/{id}`

## Request

- Base URL: `https://api.gogoscreen.com/api/v1`
- URL: `https://api.gogoscreen.com/api/v1/storyboards/{id}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

The plan a render can be made from: the job envelope (`state`, `pollAfterMs`, and `progress`, the current step and whole percent while it plans), the beats with a short-lived screenshot URL each, the steps the run could not resolve, the hint-coverage report — what the hint asked for that the beats do not show — and `lengthFit`, what the chosen length did to the plan. Poll until `state` is terminal, then read `beats`.

## Path parameters

- `id` string, uuid, required

## Response `200`

One storyboard

- object
  - `appEntryUrl` string, nullable, required: Where the walkthrough was actually recorded, when a sign-in proved the app is not at `targetOrigin` — a product at app.example.com for a site at example.com. Null means the two are the same place.
  - `beats` object[], required
    - `beatId` string
    - `narration` string, nullable
    - `screenshotUrl` string, nullable
  - `coverage` object, required
    - `uncovered` string[], required: What the hint asked for that the beats do not show.
    - `wider` object[], required: Pages wider than the recording viewport, clipped at the right edge on camera.
  - `credentialsHeld` boolean, required: Whether the session credential the run used is still held server-side. The credential itself never leaves the server.
  - `hadCredentials` boolean, required
  - `hint` string, nullable, required
  - `lengthFit` object, nullable, required: WHAT THE PLAN DID ABOUT THE LENGTH. Null for a storyboard planned before this record existed, which is not the same as `adjusted: false`.
    - `adjusted` boolean, required: Whether the plan is shorter than the request asked for — steps trimmed, or the length's step budget used up with objectives still open. Plan again at a longer length to get the rest; planning is free.
    - `beatBudget` number, nullable, required: The steps that length can hold. An Auto plan derives it from `seconds`; a fixed length takes its own preset's.
    - `beatsDropped` number, required: Steps trimmed off the end because the length could not hold them.
    - `beatsKept` number, required: Steps in `beats`, which is what the render will show.
    - `beatsPlanned` number, required: Steps the run proved, before anything was trimmed.
    - `maxSeconds` number, nullable, required: The ceiling an Auto plan was budgeted against, or null when a fixed length was chosen.
    - `note` string, nullable, required: The sentence to show the customer, e.g. "Plan adjusted to fit 60 seconds: 10 of 13 steps kept." Null when nothing was adjusted.
    - `plannedSeconds` number, nullable, required: What the kept steps are worth in seconds — what the video will run to, before the read is measured.
    - `seconds` number, nullable, required: The length everything below was decided from: the fixed length, or the Auto ceiling.
    - `targetSeconds` number, nullable, required: The fixed length this plan was made for, or null when it was planned as Auto.
  - `storyboard` object, required
    - `artifactsExpired` boolean, required: The work succeeded but its files were deleted at the end of the retention period.
    - `cancellable` boolean, required
    - `cost` object, required
      - `secondsCharged` number, nullable, required
      - `secondsReserved` number, required
      - `watermark` boolean, required
    - `createdAt` string, date-time, nullable, required
    - `error` object, nullable, required
      - `code` string, required
      - `reason` string, nullable, required
      - `retryable` boolean, required
      - `terminal` boolean, required
    - `expiresAt` string, date-time, nullable, required
    - `finishedAt` string, date-time, nullable, required
    - `id` string, required
    - `idempotencyKey` string, nullable, required
    - `internalStatus` string, required: A finer-grained status word. Informational; branch on `state`.
    - `kind` string, required: walkthrough.render | walkthrough.storyboard | marketing.export | marketing.generation | marketing.source_scan | marketing.source_operation
    - `pollAfterMs` number, nullable, required: Wait this long before polling again; null once the state is terminal.
    - `progress` object, nullable, required: HOW FAR THE WORK HAS GOT, as last reported, or null — null while nothing has been recorded yet and null for every terminal state, because a finished job is 100 by definition and a failed one has no bar to draw.
      - `at` string, nullable, required: When it was reported. A reading that has stopped moving means the work has, not that the bar is broken.
      - `percent` number, required: 0 to 100, as last reported for this job. It never goes backwards. Draw exactly this number: nothing here is interpolated and a client that animates between readings is inventing progress.
      - `stage` string, required: A short label for the current step. Show it; do not branch on it.
    - `requestId` string, nullable, required
    - `result` object, nullable, required
      - `artifacts` object[], required
        - `bytes` number, nullable, required
        - `expiresAt` string, date-time, nullable, required
        - `sha256` string, nullable, required
        - `type` string, required
        - `url` string, nullable, required
      - `durationSeconds` number, nullable, required
    - `stage` string, nullable, required
    - `startedAt` string, date-time, nullable, required
    - `state` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled', required: The five public states. Poll until one of succeeded/failed/cancelled.
  - `stuckSteps` object[], required
  - `summary` string, nullable, required
  - `targetOrigin` string, nullable, required
  - `targetPath` string, nullable, required
  - `title` string, nullable, required

## Other responses

- `400`: `validation_failed` — That request is not valid.
- `401`: `unauthorized` — Authentication is required.
- `403`: `forbidden_scope` — This credential does not carry the scope this operation needs.
- `404`: `not_found` — No such resource.
- `429`: `rate_limited` — Too many requests. Try again shortly.
- `500`: `internal_error` — Something went wrong. Try again.

---

[API](https://skmtc.dev/gogoscreen/apis/gogoscreen-api.md) · [All operations](https://skmtc.dev/gogoscreen/apis/gogoscreen-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gogoscreen/apis/gogoscreen-api/revisions/2fd812319d75?raw)