storyboards.get

One storyboard

GET/storyboards/{id}

Operation: storyboards.get
MCP tool: storyboards_get

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.

curl 'https://api.gogoscreen.com/api/v1/storyboards/3f2b0c1a-9d4e-4a61-b8c2-000000000024' \
  -H "Authorization: Bearer $GOGOSCREEN_API_KEY"

A request to this operation.

json

{
  "storyboard": {
    "id": "3f2b0c1a-9d4e-4a61-b8c2-000000000024",
    "kind": "walkthrough.storyboard",
    "state": "running",
    "internalStatus": "running",
    "stage": null,
    "progress": {
      "stage": "starting",
      "percent": 4,
      "at": "2026-09-21T11:23:00.000Z"
    },
    "error": null,
    "result": null,
    "cost": {
      "secondsReserved": 0,
      "secondsCharged": null,
      "watermark": false
    },
    "artifactsExpired": false,
    "cancellable": true,
    "idempotencyKey": "storyboard-1790012026408",
    "requestId": null,
    "createdAt": "2026-09-21T11:21:00.000Z",
    "startedAt": "2026-09-21T11:21:00.000Z",
    "finishedAt": null,
    "expiresAt": "2026-09-21T11:22:00.000Z",
    "pollAfterMs": 2500
  },
  "title": null,
  "summary": null,
  "hint": "Show the protocol registries page.",
  "targetOrigin": "https://www.iana.org",
  "targetPath": "/",
  "appEntryUrl": null,
  "hadCredentials": false,
  "credentialsHeld": false,
  "beats": [],
  "stuckSteps": [],
  "coverage": {
    "uncovered": [],
    "wider": []
  },
  "lengthFit": null
}

200 response, captured from a real call. Ids, timestamps and signed URLs are replaced; the shape is untouched.

At a glance

Fact	Detail
Scopes	`storyboards:read`
Credentials	a signed in dashboard session or an API key.
Rate limit	600 requests a minute per credential, in the `read` class.
Idempotency	Not applicable. This operation changes nothing.
MCP tool	`storyboards_get`
Always sets	`Cache-Control: private, no-store`

Path parameters

Name	Type	Required	Description
id	string	Required	The resource `id`, from a create answer or the matching list.format: uuid

Response

Answers 200. Every answer also carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, and every error body carries a requestId.

200 OK

One storyboard

Name Type Description

appEntryUrl string | null 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[]

beatId string

narration string | null

screenshotUrl string | null

coverage object

uncovered string[] What the hint asked for that the beats do not show.

wider object[] Pages wider than the recording viewport, clipped at the right edge on camera.

credentialsHeld boolean Whether the session credential the run used is still held server-side. The credential itself never leaves the server.

hadCredentials boolean

hint string | null

lengthFit object | null WHAT THE PLAN DID ABOUT THE LENGTH. Null for a storyboard planned before this record existed, which is not the same as adjusted: false.

10 fields inside lengthFit

Name	Type	Description
adjusted	boolean	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 \| null	The steps that length can hold. An Auto plan derives it from `seconds`; a fixed length takes its own preset's.
beatsDropped	number	Steps trimmed off the end because the length could not hold them.
beatsKept	number	Steps in `beats`, which is what the render will show.
beatsPlanned	number	Steps the run proved, before anything was trimmed.
maxSeconds	number \| null	The ceiling an Auto plan was budgeted against, or null when a fixed length was chosen.
note	string \| null	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 \| null	What the kept steps are worth in seconds — what the video will run to, before the read is measured.
seconds	number \| null	The length everything below was decided from: the fixed length, or the Auto ceiling.
targetSeconds	number \| null	The fixed length this plan was made for, or null when it was planned as Auto.

storyboard object

35 fields inside storyboard

Name Type Description

artifactsExpired boolean The work succeeded but its files were deleted at the end of the retention period.

cancellable boolean

cost object

secondsCharged number | null

secondsReserved number

watermark boolean

createdAt string | null format: date-time

error object | null

code string

reason string | null

retryable boolean

terminal boolean

expiresAt string | null format: date-time

finishedAt string | null format: date-time

id string

idempotencyKey string | null

internalStatus string A finer-grained status word. Informational; branch on state.

pollAfterMs number | null Wait this long before polling again; null once the state is terminal.

progress object | null 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 | null When it was reported. A reading that has stopped moving means the work has, not that the bar is broken.

percent number 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 A short label for the current step. Show it; do not branch on it.

requestId string | null

result object | null

7 fields inside result

Name	Type	Description
artifacts	object[]
bytes	number \| null
expiresAt	string \| null	format: date-time
sha256	string \| null
type	string
url	string \| null
durationSeconds	number \| null

stage string | null

startedAt string | null format: date-time

state string The five public states. Poll until one of succeeded/failed/cancelled.one of: queued, running, succeeded, failed, cancelled

stuckSteps object[]

summary string | null

targetOrigin string | null

targetPath string | null

title string | null

200 OK headers
Header	Meaning
`Cache-Control`	Always `private, no-store`.

Errors

Every refusal is { error: { code, message, details?, requestId } }. Branch on code, never on the sentence. The full catalogue is at Errors.

Code	Status	When it happens	What to do
validation_failed	400	The merged path, query and body did not match the operation's schema. The schemas are strict, so an unknown field is a failure rather than something ignored, and a string carrying half of a character is refused before it can be stored.	Read `details.issues`. Each entry carries a `path`, a `message` and a machine readable `code`. Fix every named field and send the request again; the same body always fails the same way.
unauthorized	401	No credential was presented, or the key is unknown, revoked or expired, or an `X-API-Key` header carried something that is not an API key. `details.reason` says which.	Send `Authorization: Bearer gsk_live_…`. A revoked or expired key never starts working again, so issue a new one in the developer console. Put a dashboard session token in `Authorization`, never in `X-API-Key`.
forbidden_scope	403	The credential does not carry every scope the operation declares, or it is the wrong kind of credential for it. `keys.` and `assistant.` are user only and can never be called by a key.	`details.requiredScopes` and `details.missingScopes` name what is missing. A key's scopes cannot be changed after it is issued, so create a new key with them. When `details.allowedActors` is present, no key can call this operation at all.
not_found	404	No resource of that id belongs to this account. A resource that belongs to somebody else answers 404 as well, never 403.	Check the id. Do not treat this as a permissions problem.
rate_limited	429	The credential's per minute budget, the account's per minute ceiling, or a daily cap was exceeded. `details.scope` is `minute`, `day` or `account`, or `global` when the product's own daily cap on voice previews is spent.	Wait the `Retry-After` seconds and retry. `details.limit` and `details.resetAt` say what was hit and when it reopens. The `RateLimit-*` headers on every answer let a client pace itself before it gets here.
internal_error	500	An unhandled failure inside this API. The original message is logged and never answered.	Retry once, then quote `requestId` to support. A 5xx deletes the idempotency claim rather than storing it, so retrying under the same key is safe.