renders.get

One render

GET/renders/{id}

Operation: renders.get
MCP tool: renders_get

The state of one render, as the standard job envelope: state is one of queued/running/succeeded/failed/cancelled whatever its finer-grained status, progress is the current step and whole percent while it runs, cost says what it held and what it was charged, and pollAfterMs says how long to wait before asking again. The video itself is not here — ask renders.download for a link.

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

A request to this operation.

json

{
  "render": {
    "id": "3f2b0c1a-9d4e-4a61-b8c2-000000000025",
    "kind": "walkthrough.render",
    "state": "running",
    "internalStatus": "running",
    "stage": null,
    "progress": {
      "stage": "starting",
      "percent": 3,
      "at": "2026-09-21T11:24:00.000Z"
    },
    "error": null,
    "result": null,
    "cost": {
      "secondsReserved": 30,
      "secondsCharged": null,
      "watermark": false
    },
    "artifactsExpired": false,
    "cancellable": true,
    "idempotencyKey": "render-1790012026461",
    "requestId": null,
    "createdAt": "2026-09-21T11:21:00.000Z",
    "startedAt": "2026-09-21T11:21:00.000Z",
    "finishedAt": null,
    "expiresAt": null,
    "pollAfterMs": 2500
  }
}

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

At a glance

Fact	Detail
Scopes	`renders: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	`renders_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 render

Name Type Description

render object

35 fields inside render

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

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.