--- title: "List tool executions" method: GET path: "/v1/tools/executions" tags: ["Tools"] --- # List tool executions `GET /v1/tools/executions` List tool executions started via the API, most recently created first. Use `selfOnly=true` to restrict results to the calling API key's user; otherwise all executions for the team are returned. Cursor-paginated; see the [Pagination](/pagination) guide. Executions remain listable indefinitely (including those older than 7 days). For efficiency this list does not re-sign result download URLs, so `downloadUrl`/`thumbnailUrl` reflect the last time they were signed and may be expired (always check `downloadUrlExpiresAt`). To obtain a fresh signed URL, GET the individual execution (`GET /v1/tools/executions/{toolExecutionId}`) or hydrate the file (`GET /v1/files/{fileId}` / `POST /v1/files/{fileId}/hydrate`). ## Query parameters - `limit` integer - `cursor` string - `selfOnly` boolean ## Response `200` Paginated list of tool executions. - ToolExecutionListResponse — Paginated list of API-started tool executions, most recently created first. - `toolExecutions` ExecutedTool[], required - `toolExecutionId` string, required — Execution id matching the original request. - `status` 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled', required — Lifecycle status shared by every asynchronous job (tool executions, workflow runs, remix actions, project exports, and timeline interchange jobs). `pending` and `running` are in-progress; `succeeded`, `failed`, and `cancelled` are terminal. - `toolType` string, required — Tool name (e.g. `GENERATE_IMAGE`, `TEXT_TO_SPEECH`). - `progressPercentage` number, required — Completion progress for the current attempt (0-100). Always `100` when `status` is `succeeded`. - `attemptIndex` integer, required — Zero-based index of the current or most recent execution attempt. - `results` ToolSuccessResult[], required — One entry per generated result. Always present; empty until `status` is `succeeded`, then one entry per generated file (each with signed URLs and a hydrated `file`). - `fileId` string, required — File id for the generated asset. - `type` 'IMAGE' | 'VIDEO' | 'AUDIO' | 'PDF' | 'SLIDESHOW' | 'TEXT' | 'LOTTIE', required — File type. `TEXT` covers plain-text and editor-interchange documents; `LOTTIE` is a JSON animation. - `downloadUrl` string, uri, nullable, required — Private signed download URL for the generated file, valid for 7 days from when it was signed. Provided at the top level for convenience so you don't have to read it out of `file`. When you GET a single execution it is automatically re-signed if within an hour of expiring; list endpoints do not re-sign, so there it may be expired (check `downloadUrlExpiresAt`). See `downloadUrlExpiresAt` for the exact expiry. Null only in the rare case that the highest-quality rendition is still finalizing. - `downloadUrlExpiresAt` integer, nullable, required — Seconds since epoch (Unix timestamp) when `downloadUrl` expires. Null only when `downloadUrl` is null. - `thumbnailUrl` string, uri, nullable, required — Private signed thumbnail URL for the generated file, valid for 7 days from when it was signed. Provided at the top level for convenience so you don't have to read it out of `file`. Re-signed on the same terms as `downloadUrl` (single-execution GET re-signs when near expiry; list endpoints do not). Null for file types that have no thumbnail (e.g. audio). - `thumbnailUrlExpiresAt` integer, nullable, required — Seconds since epoch (Unix timestamp) when `thumbnailUrl` expires. Null when there is no thumbnail URL. - `file` FileInfo, required — Metadata for a generated file. Obtain ids from tool results or `GET /v1/files`. - `fileId` string, required — File id (e.g. `vg_file_...`). - `type` 'IMAGE' | 'VIDEO' | 'AUDIO' | 'PDF' | 'SLIDESHOW' | 'TEXT' | 'LOTTIE' — File type. `TEXT` covers plain-text and editor-interchange documents; `LOTTIE` is a JSON animation. - `scope` 'GLOBAL' | 'PROJECT' | 'EXPORT' | 'TEMPORARY' | 'ENTITY', required — File scope. - `GLOBAL`: user-uploaded or standalone generated files that persist indefinitely. - `PROJECT`: project-specific files (e.g. text-to-speech clips in a generated project). - `EXPORT`: project exports. - `TEMPORARY`: short-lived files guaranteed to be available for 24 hours, after which they may be archived at any time. Not analyzed (no description, transcript, or embedding). - `ENTITY`: files attached to a reusable entity (e.g. a voice sample for an actor), shared across your team. - `displayName` string — Display name for the file. - `description` string, nullable - `durationSeconds` number, nullable — Duration in seconds for video and audio files. Null for images. - `transcript` Transcript — A transcript of an audio file, as timed words in order. - `languageCode` string, nullable — Optional BCP-47 language code of the spoken audio (e.g. `en`, `es`). Used to tag the transcript's language; omit if unknown. - `words` TranscriptWord[], required — The transcript words, sorted by `startSeconds` and non-overlapping. Must contain at least one word. - `startSeconds` number, required — Start time of the word in seconds from the beginning of the audio. - `endSeconds` number, required — End time of the word in seconds from the beginning of the audio. Must be greater than `startSeconds`. - `word` string, required — The spoken word, used verbatim for narration timing and captions. - `transcriptText` string, nullable — Plain transcript text for video and audio files, when available. Null for images or when no transcript has been generated. - `downloadUrl` string, uri, nullable — Private signed URL for the highest-quality downloadable rendition, provided at the top level for convenience. Valid for 7 days from when it was signed. `null` when the rendition is still processing or the URL has not been signed yet. See `downloadUrlExpiresAt` for the exact expiry and `downloadSource` for the full rendition metadata; call `POST /v1/files/{fileId}/hydrate` to refresh it. - `downloadUrlExpiresAt` integer, nullable — Seconds since epoch (Unix timestamp) when `downloadUrl` expires. `null` when `downloadUrl` is null. - `thumbnailUrl` string, uri, nullable — Private signed URL for the thumbnail rendition, provided at the top level for convenience. Valid for 7 days from when it was signed. `null` for file types that have no thumbnail (e.g. audio) or when it has not been signed yet. See `thumbnailSource` for the full rendition metadata. - `thumbnailUrlExpiresAt` integer, nullable — Seconds since epoch (Unix timestamp) when `thumbnailUrl` expires. `null` when `thumbnailUrl` is null. - `thumbnailSource` FileSource — A rendition source for a file (e.g. thumbnail, preview, download). Contains a signed URL and metadata. - `status` 'pending' | 'ready' | 'failed' | 'skipped', required — `pending`: asset is still processing or has not been hydrated yet. `ready`: signed URL is available. `failed`: rendition generation failed. `skipped`: rendition does not apply to this file type (e.g. thumbnail for audio). - `url` string, nullable — Signed URL. Present when status is `ready` and file has been recently hydrated. If missing, call the hydrate endpoint. - `expiresAt` integer, nullable — Seconds since epoch (Unix timestamp) when the signed URL expires. - `width` integer, nullable — Rendition width in pixels, when known. - `height` integer, nullable — Rendition height in pixels, when known. - `fileBytes` integer, nullable — File size in bytes, when known. - `previewSource` FileSource — A rendition source for a file (e.g. thumbnail, preview, download). Contains a signed URL and metadata. - `status` 'pending' | 'ready' | 'failed' | 'skipped', required — `pending`: asset is still processing or has not been hydrated yet. `ready`: signed URL is available. `failed`: rendition generation failed. `skipped`: rendition does not apply to this file type (e.g. thumbnail for audio). - `url` string, nullable — Signed URL. Present when status is `ready` and file has been recently hydrated. If missing, call the hydrate endpoint. - `expiresAt` integer, nullable — Seconds since epoch (Unix timestamp) when the signed URL expires. - `width` integer, nullable — Rendition width in pixels, when known. - `height` integer, nullable — Rendition height in pixels, when known. - `fileBytes` integer, nullable — File size in bytes, when known. - `downloadSource` FileSource — A rendition source for a file (e.g. thumbnail, preview, download). Contains a signed URL and metadata. - `status` 'pending' | 'ready' | 'failed' | 'skipped', required — `pending`: asset is still processing or has not been hydrated yet. `ready`: signed URL is available. `failed`: rendition generation failed. `skipped`: rendition does not apply to this file type (e.g. thumbnail for audio). - `url` string, nullable — Signed URL. Present when status is `ready` and file has been recently hydrated. If missing, call the hydrate endpoint. - `expiresAt` integer, nullable — Seconds since epoch (Unix timestamp) when the signed URL expires. - `width` integer, nullable — Rendition width in pixels, when known. - `height` integer, nullable — Rendition height in pixels, when known. - `fileBytes` integer, nullable — File size in bytes, when known. - `hlsSource` FileSource — A rendition source for a file (e.g. thumbnail, preview, download). Contains a signed URL and metadata. - `status` 'pending' | 'ready' | 'failed' | 'skipped', required — `pending`: asset is still processing or has not been hydrated yet. `ready`: signed URL is available. `failed`: rendition generation failed. `skipped`: rendition does not apply to this file type (e.g. thumbnail for audio). - `url` string, nullable — Signed URL. Present when status is `ready` and file has been recently hydrated. If missing, call the hydrate endpoint. - `expiresAt` integer, nullable — Seconds since epoch (Unix timestamp) when the signed URL expires. - `width` integer, nullable — Rendition width in pixels, when known. - `height` integer, nullable — Rendition height in pixels, when known. - `fileBytes` integer, nullable — File size in bytes, when known. - `isPublicPreviewEnabled` boolean — Whether public preview is enabled for this file. When true, `staticPublicPreviewSource` is populated for all file types. For video and audio, `publicHlsUrl` and `publicPlaybackId` are also populated once embed streaming is ready. - `staticPublicPreviewSource` FileSource — A rendition source for a file (e.g. thumbnail, preview, download). Contains a signed URL and metadata. - `status` 'pending' | 'ready' | 'failed' | 'skipped', required — `pending`: asset is still processing or has not been hydrated yet. `ready`: signed URL is available. `failed`: rendition generation failed. `skipped`: rendition does not apply to this file type (e.g. thumbnail for audio). - `url` string, nullable — Signed URL. Present when status is `ready` and file has been recently hydrated. If missing, call the hydrate endpoint. - `expiresAt` integer, nullable — Seconds since epoch (Unix timestamp) when the signed URL expires. - `width` integer, nullable — Rendition width in pixels, when known. - `height` integer, nullable — Rendition height in pixels, when known. - `fileBytes` integer, nullable — File size in bytes, when known. - `publicHlsUrl` string, nullable — Public HLS streaming URL for video and audio. Only present when `isPublicPreviewEnabled` is true and embed streaming is ready. Prefer `publicPlaybackId` with `@videogen/player` for embeds. - `publicPlaybackId` string, nullable — Encoded public playback id (e.g. `vg_play_...`) for video and audio embeds. Pass this to `@videogen/player` or `@videogen/player-react`. Only present when `isPublicPreviewEnabled` is true and embed streaming is ready. For a permanent direct file URL (any type), use `staticPublicPreviewSource` instead. - `sourceToolType` string — Tool type that generated this file (e.g. `GENERATE_IMAGE`, `TEXT_TO_SPEECH`). Only present when the file was created by a tool execution. - `sourceToolExecutionId` string — Execution id of the tool call that generated this file (e.g. `vg_tool_...`). Only present when the file was created by a tool execution. - `fileAnalysisMetadata` FileAnalysisMetadata — Background analysis state for a file. Background analysis populates `description`, `transcript`, `durationSeconds`, and the search embedding after a file is uploaded or generated; this object lets you render a progress indicator while it runs (and skip rendering once it's done). - `analysisLoadingState` 'UNATTEMPTED' | 'LOADING' | 'FULFILLED' | 'REJECTED', required — Coarse-grained analysis state. - `UNATTEMPTED`: analysis has not started yet. - `LOADING`: analysis is in progress. - `FULFILLED`: analysis completed successfully. `description`, `transcript`, and `durationSeconds` are now populated where applicable for the file's type. - `REJECTED`: analysis failed permanently and will not be retried. - `analysisProgressPercentage` number, required — Progress in `[0, 100]`. Always `100` when `analysisLoadingState` is `FULFILLED`. Otherwise the most recent in-flight progress reported by the analysis task (or `0` if no progress has been reported yet). - `analysisAttemptIndex` integer — Zero-based index of the current analysis task attempt. Only present while analysis is still loading (`UNATTEMPTED` or `LOADING`); omitted once analysis reaches a terminal state. - `error` ApiError, required — Standard error body returned with every non-2xx response (the `default` response of every operation). The HTTP status code conveys the error class; this body carries the details: - `400` invalid request, `401` missing or invalid API key, `403` not permitted (e.g. plan or add-on required, see `requirement`), `404` not found, `409` conflict, `429` rate limited or out of credits, `5xx` server error. Common `code` values include `invalid_request`, `invalid_api_key`, `not_authorized`, `not_found`, `insufficient_credits`, and `rate_limited`. Always branch on `code` (and `requirement.type` when present) rather than parsing `message`. - `message` string, required — Human-readable error description. For display and logging only; do not branch on its exact text. - `code` string, nullable — Machine-readable error code in snake_case (e.g. `invalid_api_key`, `insufficient_credits`). `null` when no specific code applies. - `requirement` ErrorRequirement — What is needed to resolve an error, when it can be fixed by fulfilling a specific requirement (e.g. purchasing an add-on or upgrading the plan). - `type` string, required — Machine-readable requirement type in snake_case (e.g. `purchase_add_on`, `upgrade_plan`). - `details` object — Key-value pairs with requirement-specific context (e.g. the add-on id to purchase). - `internalErrorCode` string, nullable — Opaque internal error code for debugging. Include this when contacting support. `null` when not applicable. - `hasMore` boolean, required — When true, there are more executions available. Pass `nextCursor` as the `cursor` query param to fetch the next page. - `nextCursor` string, nullable, required — Opaque cursor to fetch the next page. `null` when `hasMore` is false. ## Other responses - `default` — Error --- [API](https://skmtc.dev/videogen/apis/videogen-api.md) · [All operations](https://skmtc.dev/videogen/apis/videogen-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/videogen/videogen-api/revisions/33dda0455d67/schema)