---
title: "tool_execution.succeeded"
method: POST
path: "tool_execution.succeeded"
tags: ["Webhook events"]
---

# tool_execution.succeeded

`POST tool_execution.succeeded` (webhook)

Delivered when a tool execution completes successfully.

## Payload

- ToolExecutionWebhookPayload — Delivered to your webhook endpoint when a tool execution reaches a terminal state. The shape mirrors the `ExecutedTool` response with the addition of `event` and `occurredAt`.
  - `event` 'tool_execution.succeeded' | 'tool_execution.failed' | 'tool_execution.cancelled', required — Webhook event types for tool execution lifecycle.
  - `toolExecutionId` string, required — Execution id matching the original request.
  - `occurredAt` integer, required — Seconds since epoch (Unix timestamp) when the execution reached a terminal state.
  - `toolType` string, required — Tool name (e.g. `GENERATE_IMAGE`, `TEXT_TO_SPEECH`).
  - `results` ToolSuccessResult[] — One entry per generated result, each with a hydrated `file`. Present only on `tool_execution.succeeded`.
    - `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 — 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.

## Acknowledgement `200`

Acknowledge receipt

---

[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)